{"_id":"@animatrous/shadow-boxer","name":"@animatrous/shadow-boxer","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@animatrous/shadow-boxer","version":"0.1.0","type":"module","description":"Browser-native AI WebAssembly boxing physics engine and real-time biomechanics tracker.","license":"AGPL-3.0-only","author":{"name":"Shadow Boxer Contributors"},"homepage":"https://github.com/code-dibyajyotirout/shadow-boxer-npm-package#readme","repository":{"type":"git","url":"git+https://github.com/code-dibyajyotirout/shadow-boxer-npm-package.git"},"bugs":{"url":"https://github.com/code-dibyajyotirout/shadow-boxer-npm-package/issues"},"keywords":["boxing","ai-fitness","mediapipe","webassembly","biomechanics","computer-vision","pose-estimation","signal-processing","one-euro-filter","web-audio","react","nextjs","shadow-boxing"],"main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.js","default":"./dist/index.js"},"./hooks":{"types":"./dist/hooks/index.d.ts","import":"./dist/hooks/index.js","require":"./dist/hooks/index.js","default":"./dist/hooks/index.js"},"./components":{"types":"./dist/components/index.d.ts","import":"./dist/components/index.js","require":"./dist/components/index.js","default":"./dist/components/index.js"},"./utils":{"types":"./dist/utils/index.d.ts","import":"./dist/utils/index.js","require":"./dist/utils/index.js","default":"./dist/utils/index.js"},"./types":{"types":"./dist/types/index.d.ts"},"./style.css":"./dist/style.css"},"sideEffects":["*.css"],"scripts":{"build:lib":"node scripts/build-lib.js","test":"node --test tests/*.test.mjs","typecheck":"node node_modules/typescript/lib/tsc.js --noEmit","lint":"node node_modules/typescript/lib/tsc.js --noEmit","prepublishOnly":"npm run typecheck && npm run test && npm run build:lib","clean":"rm -rf dist .next out coverage"},"peerDependencies":{"react":">=18.0.0","react-dom":">=18.0.0"},"dependencies":{"@mediapipe/tasks-vision":"^0.10.35"},"devDependencies":{"@types/node":"^20","@types/react":"^19","@types/react-dom":"^19","typescript":"^5"},"gitHead":"544f84b29becc4ceec2700ca5a6ec8e7e0a83357","_id":"@animatrous/shadow-boxer@0.1.0","_nodeVersion":"18.19.1","_npmVersion":"9.2.0","dist":{"integrity":"sha512-vg+JG6MMrwxErD9eG2yFXSg7gUggm7VaumC4ERlbOGB71YggK/vY9GPo3DFTvFUX6BQDQt9YGaToUcaKlzK+hA==","shasum":"639a8ab297cebfcc6a7c10bb2b12b945b326d51e","tarball":"https://registry.npmjs.org/@animatrous/shadow-boxer/-/shadow-boxer-0.1.0.tgz","fileCount":32,"unpackedSize":98744,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC/kqCdNscMrnrGZ1xNpSF+uEEubU7yQCZ9bFLlWrteRAIgGH6m3RVzs4QMEy6XdgOf3KNH8ERVZplk5WzWmMuwOMA="}]},"_npmUser":{"name":"animatrous","email":"animatrous@gmail.com"},"directories":{},"maintainers":[{"name":"animatrous","email":"animatrous@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/shadow-boxer_0.1.0_1788194011660_0.8035118089116677"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-31T16:33:31.383Z","0.1.0":"2026-08-31T16:33:31.790Z","modified":"2026-08-31T16:33:32.035Z"},"maintainers":[{"name":"animatrous","email":"animatrous@gmail.com"}],"description":"Browser-native AI WebAssembly boxing physics engine and real-time biomechanics tracker.","homepage":"https://github.com/code-dibyajyotirout/shadow-boxer-npm-package#readme","keywords":["boxing","ai-fitness","mediapipe","webassembly","biomechanics","computer-vision","pose-estimation","signal-processing","one-euro-filter","web-audio","react","nextjs","shadow-boxing"],"repository":{"type":"git","url":"git+https://github.com/code-dibyajyotirout/shadow-boxer-npm-package.git"},"author":{"name":"Shadow Boxer Contributors"},"bugs":{"url":"https://github.com/code-dibyajyotirout/shadow-boxer-npm-package/issues"},"license":"AGPL-3.0-only","readme":"# @animatrous/shadow-boxer\n\n> **Browser-Native AI WebAssembly Boxing Physics Engine & Real-Time Biomechanics Tracker**\n\n[![npm version](https://img.shields.io/npm/v/@animatrous/shadow-boxer.svg)](https://www.npmjs.com/package/@animatrous/shadow-boxer)\n[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)\n[![React](https://img.shields.io/badge/React-18%2B-61DAFB?logo=react&logoColor=black)](https://react.dev/)\n\n`@animatrous/shadow-boxer` is a modular, high-performance computer vision and biomechanics SDK for browser-based fitness tracking, combat sports telemetry, and motion analysis. It computes 3D punch velocity in $m/s$, instantaneous acceleration in $m/s^2$, joint extension ratios, and strike archetypes in real time at 60 FPS with zero server-side computation.\n\n---\n\n## Installation\n\n```bash\nnpm install @animatrous/shadow-boxer\n```\n\n```bash\nyarn add @animatrous/shadow-boxer\n```\n\n```bash\npnpm add @animatrous/shadow-boxer\n```\n\n---\n\n## Quick Start\n\n### 1. Import Stylesheet\n\nImport the default cyberpunk HUD styles in your application root:\n\n```typescript\nimport \"@animatrous/shadow-boxer/style.css\";\n```\n\n### 2. Full React Component Integration\n\n```tsx\nimport React from \"react\";\nimport { ShadowBoxer } from \"@animatrous/shadow-boxer\";\nimport \"@animatrous/shadow-boxer/style.css\";\n\nexport default function BoxingPage() {\n  return (\n    <main style={{ padding: 24, background: \"#06090e\", minHeight: \"100vh\" }}>\n      <ShadowBoxer\n        speedThreshold={1.5}\n        filterCutoff={1.5}\n        enableAudio={true}\n        workoutPreset=\"cardio\"\n        onStrike={(event) => {\n          console.log(\"Strike landed:\", event.type, event.metrics.velocity, \"m/s\");\n        }}\n        onComboComplete={(streak) => {\n          console.log(\"Combo completed! Current streak:\", streak);\n        }}\n      />\n    </main>\n  );\n}\n```\n\n### 3. Headless React Hook Integration (`useShadowBoxer`)\n\nBuild custom UI or 3D viewports while letting `@animatrous/shadow-boxer` handle kinematics, filtering, and classification:\n\n```tsx\nimport React from \"react\";\nimport { useShadowBoxer, PoseOverlay, MetricsDisplay } from \"@animatrous/shadow-boxer\";\n\nexport function CustomBoxingTracker() {\n  const { state, start, stop, resetMetrics, processPose } = useShadowBoxer({\n    speedThreshold: 1.5,\n    filterCutoff: 1.5,\n    enableAudio: true,\n    workoutPreset: \"all\",\n  });\n\n  return (\n    <div>\n      <MetricsDisplay\n        metrics={state.activeMetrics}\n        comboStreak={state.comboStreak}\n        highestCombo={state.highestCombo}\n        totalPunches={state.totalPunches}\n        peakVelocity={state.peakVelocity}\n        score={state.currentScore}\n      />\n      <button onClick={start}>Start Tracking</button>\n      <button onClick={stop}>Stop</button>\n    </div>\n  );\n}\n```\n\n---\n\n## Subpath Imports\n\n`@animatrous/shadow-boxer` provides modular exports for minimal bundle footprints:\n\n```typescript\n// Core Root\nimport { ShadowBoxer, useShadowBoxer, BiomechanicsEngine, OneEuroFilter } from \"@animatrous/shadow-boxer\";\n\n// Dedicated Hooks\nimport { useShadowBoxer, useAudioFX } from \"@animatrous/shadow-boxer/hooks\";\n\n// Dedicated Components\nimport { ShadowBoxer, PoseOverlay, MetricsDisplay } from \"@animatrous/shadow-boxer/components\";\n\n// Dedicated Utilities\nimport { BiomechanicsEngine, OneEuroFilter, StrikeClassifier, AudioSynthesizer } from \"@animatrous/shadow-boxer/utils\";\n\n// Dedicated Types\nimport type { Landmark3D, PunchMetrics, StrikeEvent, StanceStatus } from \"@animatrous/shadow-boxer/types\";\n```\n\n---\n\n## API Reference\n\n### `BiomechanicsEngine`\n\nStatic kinematic calculator for 3D coordinates:\n\n- `distance3D(p1: Landmark3D, p2: Landmark3D): number`\n- `calculateAngle(a: Landmark3D, b: Landmark3D, c: Landmark3D): number`\n- `computeVelocity(pPrev: Landmark3D, pCurr: Landmark3D, dtSeconds: number, scaleFactor?: number): number`\n- `computeAcceleration(vPrev: number, vCurr: number, dtSeconds: number): number`\n- `computeExtensionRatio(shoulder: Landmark3D, elbow: Landmark3D, wrist: Landmark3D): number`\n- `evaluateStance(landmarks: Landmark3D[]): StanceStatus`\n\n### `OneEuroFilter` & `LandmarkFilter3D`\n\nAdaptive low-pass filter algorithm suppressing coordinate jitter without adding latency during rapid movement:\n\n```typescript\nimport { OneEuroFilter } from \"@animatrous/shadow-boxer/utils\";\n\nconst filter = new OneEuroFilter(60, 1.5, 0.007, 1.0);\nconst smoothedX = filter.filter(rawX, performance.now());\n```\n\n### `StrikeClassifier`\n\nIdentifies five strike and defense archetypes:\n\n- `JAB/CROSS`: Extended arm along dominant axis (elbow angle > 130 degrees).\n- `HOOK`: Horizontal angular displacement with bent elbow (45 - 135 degrees).\n- `UPPERCUT`: Upward wrist trajectory with vertical flexion.\n- `SLIP`: Rapid lateral head displacement.\n- `DUCK`: Rapid downward head and torso drop.\n\n---\n\n## Security & Privacy Model\n\n`@animatrous/shadow-boxer` executes all landmark filters, mathematical calculations, and classification loops entirely inside the client-side JavaScript runtime. No camera frames, biometric measurements, or telemetry data are stored or transmitted across network sockets.\n\n---\n\n## License\n\nThis project is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0)**. See the [LICENSE](LICENSE) file for details.\n","readmeFilename":"README.md","_rev":"1-7f52951213e394105d53f4043955ef9e"}