@zencemarketing/spin-scratch-sdk 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,716 @@
+# SpinWheel SDK + ScratchCard SDK
+
+A dynamic, configurable **Spin & Win** wheel and **Scratch Card** SDK for **Vanilla JS** and **React** (with full **TypeScript** support).
+
+Package name: `@zencemarketing/spin-scratch-sdk`
+
+---
+
+## Who is this for?
+
+If you are a client developer, you generally only need to:
+
+1. Install the package
+2. Render a container (`<div id="..." />`)
+3. Call `SpinWheel.init(...)` or `ScratchCard.init(...)` (Vanilla) **or** use the React wrappers
+
+Everything else (HTML structure, styles, DOM events, animations) is handled internally by the SDK.
+
+## Requirements
+
+- Browser environment (needs `window` and `document`)
+- Node.js >= 16 for building this SDK
+
+If you use SSR frameworks (Next.js, Remix), initialize the widgets only on the client (e.g. inside `useEffect`).
+
+## Features
+
+| Feature | Details |
+|---|---|
+| **Dynamic segments** | 2–N segments – just pass an array |
+| **Fully configurable** | 40+ options for SpinWheel, 50+ for ScratchCard |
+| **Spin physics** | Configurable duration, spin count, easing |
+| **Spin limit** | Restrict number of spins per session |
+| **Win card overlay** | Auto-generated coupon code, copy button, configurable redeem CTA |
+| **Confetti** | Toggleable confetti with custom colors and count |
+| **Appearance** | Customize ring, pointer, button, background, shadows, animations |
+| **Callbacks** | `onSpinStart`, `onSpinEnd`, `onRedeem`, `onSpinLimitReached` |
+| **Runtime updates** | `updateOptions()`, `updateSegments()`, `updatePrize()` |
+| **React support** | Thin wrapper with `ref` for imperative control |
+| **Zero dependencies** | CSS is auto-injected; fonts loaded from Google Fonts |
+
+---
+
+## Installation
+
+### Install from npm (when published)
+
+```bash
+npm i @zencemarketing/spin-scratch-sdk
+```
+
+### Use locally (not published yet)
+
+In your client app `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@zencemarketing/spin-scratch-sdk": "file:../path-to/ZenceGamification/sdk"
+  }
+}
+```
+
+Then:
+
+```bash
+# In the SDK folder
+npm i
+npm run build
+
+# In the client folder
+npm i
+```
+
+Note: Always point `file:` to the SDK **root folder** (the one that contains `package.json`), not `dist/`.
+
+## TypeScript support
+
+This SDK ships TypeScript declarations out of the box — no `@types/` package needed.
+
+### Two entry points
+
+| Entry | Import path | Use case |
+|---|---|---|
+| **Main** | `@zencemarketing/spin-scratch-sdk` | Vanilla JS/TS, factory React |
+| **React** | `@zencemarketing/spin-scratch-sdk/react` | Pre-wired React components |
+
+### Recommended import for React + TypeScript
+
+```tsx
+import {
+  SpinWheelReact,
+  ScratchCardReact,
+  type SpinWheelReactProps,
+  type ScratchCardReactProps,
+  type SpinWheelReactHandle,
+  type ScratchCardReactHandle,
+  type SegmentConfig,
+  type ScratchPrize,
+} from '@zencemarketing/spin-scratch-sdk/react';
+```
+
+### Recommended import for Vanilla TypeScript
+
+```ts
+import {
+  SpinWheel,
+  ScratchCard,
+  type SpinWheelOptions,
+  type ScratchCardOptions,
+  type SegmentConfig,
+  type ScratchPrize,
+} from '@zencemarketing/spin-scratch-sdk';
+```
+
+### Key type tips
+
+- **Segment shape**: Required fields are `label` and `color` (NOT `name`)
+- **React props**: Use `SpinWheelReactProps` / `ScratchCardReactProps` — these already omit `container` (the SDK handles it). **Do NOT use** `Omit<SpinWheelOptions, 'container'>` manually.
+- **Ref handles**: Use `SpinWheelReactHandle` / `ScratchCardReactHandle` for `useRef` generic.
+
+Tip: If you hover on `SpinWheel.init` and you only see `options: SpinWheelOptions`, that’s normal. To see all available fields:
+
+- Use IntelliSense inside `SpinWheel.init({ ... })` (Ctrl+Space)
+- Or Ctrl/Cmd-click `SpinWheelOptions` to open the full type
+
+---
+
+## Quick Start (Vanilla JS)
+
+### Option A: Use the UMD bundle in plain HTML
+
+When the package is published, you can use a CDN like `unpkg`:
+
+```html
+<div id="my-wheel"></div>
+
+<!-- Uses the "unpkg" entry from package.json -->
+<script src="https://unpkg.com/@zencemarketing/spin-scratch-sdk"></script>
+
+<script>
+  var SpinWheel = window.SpinWheelSDK.SpinWheel;
+
+  var wheel = SpinWheel.init({
+    container: '#my-wheel',
+    segments: [
+      { label: 'Free Gift',       color: '#55efc4', icon: '🎁', title: 'Free Gift',       worth: '₹299' },
+      { label: 'Surprise Reward', color: '#81ecec', icon: '✨', title: 'Surprise Reward', worth: '₹199' },
+      { label: 'Better Luck',     color: '#dfe6e9', icon: '🌟', title: 'Better Luck',     worth: '' },
+    ],
+    headerTitle: 'Spin & Win',
+    headerSubtitle: 'Try your luck!',
+    onSpinEnd: function (prize, index) {
+      console.log('Won:', prize, 'at index', index);
+    },
+  });
+
+  // Optional: wheel.spin();
+</script>
+```
+
+### Option B: Import in a bundler app (Vite/Webpack/etc.)
+
+```js
+import { SpinWheel } from '@zencemarketing/spin-scratch-sdk';
+
+const wheel = SpinWheel.init({
+  container: '#my-wheel',
+  segments: [
+    { label: 'Prize 1', color: '#55efc4' },
+    { label: 'Prize 2', color: '#81ecec' },
+  ],
+});
+```
+
+## Quick Start (React)
+
+There are two ways to use this SDK in React.
+
+### Option A (recommended): Import from `/react` subpath
+
+The simplest way — components are pre-wired, fully typed, and just work:
+
+```tsx
+import React, { useRef } from 'react';
+import {
+  SpinWheelReact,
+  type SpinWheelReactHandle,
+  type SegmentConfig,
+} from '@zencemarketing/spin-scratch-sdk/react';
+
+export default function App() {
+  const ref = useRef<SpinWheelReactHandle>(null);
+
+  const segments: SegmentConfig[] = [
+    { label: 'Free Gift', color: '#55efc4', icon: '🎁', title: 'Free Gift', worth: '₹299' },
+    { label: 'Surprise',  color: '#81ecec', icon: '✨', title: 'Surprise',  worth: '₹199' },
+    { label: 'Better Luck', color: '#dfe6e9', icon: '🌟' },
+  ];
+
+  return (
+    <SpinWheelReact
+      ref={ref}
+      headerTitle="Spin & Win"
+      segments={segments}
+      onSpinEnd={(prize: SegmentConfig, idx: number) => console.log('Won:', prize, idx)}
+    />
+  );
+}
+```
+
+### Option B: Factory function (advanced)
+
+If you need more control or want to avoid the `/react` subpath:
+
+```tsx
+import React, { useRef } from 'react';
+import { createSpinWheelReact, type SpinWheelReactHandle } from '@zencemarketing/spin-scratch-sdk';
+
+const SpinWheelReact = createSpinWheelReact(React);
+
+export default function App() {
+  const ref = useRef<SpinWheelReactHandle>(null);
+
+  return (
+    <SpinWheelReact
+      ref={ref}
+      headerTitle="Spin & Win"
+      segments={[
+        { label: 'Free Gift', color: '#55efc4', icon: '🎁', title: 'Free Gift', worth: '₹299' },
+        { label: 'Surprise',  color: '#81ecec', icon: '✨', title: 'Surprise',  worth: '₹199' },
+      ]}
+      onSpinEnd={(prize, idx) => console.log('Won:', prize, idx)}
+    />
+  );
+}
+```
+
+### Option B: Use Vanilla API inside `useEffect`
+
+This gives you full control, but you must clean up on unmount.
+
+```jsx
+import React, { useEffect } from 'react';
+import { SpinWheel } from '@zencemarketing/spin-scratch-sdk';
+
+export default function App() {
+  useEffect(() => {
+    const wheel = SpinWheel.init({
+      container: '#spin-wheel-container',
+      segments: [
+        { label: 'Prize 1', color: '#55efc4' },
+        { label: 'Prize 2', color: '#81ecec' },
+      ],
+    });
+
+    return () => {
+      wheel.destroy();
+    };
+  }, []);
+
+  return <div id="spin-wheel-container" />;
+}
+```
+
+Tip (React StrictMode): React may mount/unmount twice in development. Always keep the cleanup (`destroy()`) to avoid duplicate widgets.
+
+---
+
+## ScratchCard quick start (Vanilla)
+
+```js
+import { ScratchCard } from '@zencemarketing/spin-scratch-sdk';
+
+const card = ScratchCard.init({
+  container: '#scratch-card-container',
+  prize: { name: 'Gift Voucher', icon: '🎁', label: 'Congratulations!' },
+  onReveal: (prize) => console.log('Revealed:', prize),
+});
+```
+
+## ScratchCard quick start (React)
+
+```tsx
+import React, { useRef } from 'react';
+import {
+  ScratchCardReact,
+  type ScratchCardReactHandle,
+  type ScratchPrize,
+} from '@zencemarketing/spin-scratch-sdk/react';
+
+export default function App() {
+  const ref = useRef<ScratchCardReactHandle>(null);
+
+  return (
+    <ScratchCardReact
+      ref={ref}
+      prize={{ name: 'Gift Voucher', icon: '🎁', label: 'Congratulations!' }}
+      onReveal={(prize: ScratchPrize) => console.log('Revealed:', prize)}
+    />
+  );
+}
+```
+
+Or using the factory pattern:
+
+```tsx
+import React, { useRef } from 'react';
+import { createScratchCardReact, type ScratchCardReactHandle } from '@zencemarketing/spin-scratch-sdk';
+
+const ScratchCardReact = createScratchCardReact(React);
+
+export default function App() {
+  const ref = useRef<ScratchCardReactHandle>(null);
+
+  return (
+    <ScratchCardReact
+      ref={ref}
+      prize={{ name: 'Gift Voucher', icon: '🎁', label: 'Congratulations!' }}
+      onReveal={(prize) => console.log('Revealed:', prize)}
+    />
+  );
+}
+```
+
+## SpinWheel API Reference
+
+### `SpinWheel.init(options)` → `SpinWheelInstance`
+
+#### Core Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `container` | `string \| HTMLElement` | *required* | CSS selector or DOM element to mount into |
+| `segments` | `Array<Segment>` | *required* | Array of prize segments (min 2) |
+| `winningIndex` | `number \| null` | `null` | Pre-determined winning index. Overridden by `forceIndex` in `.spin()` |
+
+#### Spin Behavior
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `spinDuration` | `number` | `5000` | Total spin animation duration (ms) |
+| `minSpins` | `number` | `5` | Minimum full rotations |
+| `maxSpins` | `number` | `8` | Maximum full rotations |
+| `spinLimit` | `number \| null` | `null` | Max spins allowed (`null` = unlimited) |
+
+#### Header UI
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `headerTitle` | `string \| null` | `null` | Title above the wheel |
+| `headerSubtitle` | `string \| null` | `null` | Subtitle below the title |
+| `titleColor` | `string \| null` | `null` | Custom title color (uses `theme.goldLight` if null) |
+| `subtitleColor` | `string \| null` | `null` | Custom subtitle color (uses `theme.textMuted` if null) |
+
+#### Hub / Center
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `hubLabel` | `string` | `'Spin & win'` | Text inside the center hub |
+| `hubIcon` | `string` | `'▲'` | Icon inside the center hub |
+
+#### Spin Button
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `showButton` | `boolean` | `true` | Show the external SPIN! button |
+| `buttonText` | `string` | `'SPIN!'` | Button label text |
+
+#### Wheel Appearance
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `backgroundColor` | `string \| null` | `null` | Container background color |
+| `backgroundImage` | `string \| null` | `null` | Background image URL |
+| `ringColor` | `string \| null` | `null` | Wheel ring color |
+| `ringShadow` | `boolean` | `true` | Enable ring shadow/glow |
+| `ringAnimation` | `boolean` | `true` | Enable pulsing ring animation |
+| `pointerColor` | `string \| null` | `null` | Pointer/arrow color |
+| `buttonColor` | `string \| null` | `null` | Spin button gradient color |
+| `buttonShadow` | `boolean` | `true` | Enable button shadow |
+| `buttonAnimation` | `boolean` | `true` | Enable button hover/active animations |
+
+#### Win Card
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `showWinCard` | `boolean` | `true` | Show win card overlay after spin |
+| `generateCode` | `boolean` | `true` | Auto-generate a random coupon code |
+| `codeLength` | `number` | `9` | Length of auto-generated codes |
+| `redeemUrl` | `string \| null` | `null` | URL for redeem button |
+| `winCardBrandLabel` | `string \| null` | `null` | Brand label on win card (uses `hubLabel` if null) |
+| `winCardWorthLabel` | `string` | `'WORTH'` | Label before worth value |
+| `winCardRedeemButtonText` | `string` | `'Redeem Now'` | Redeem button text |
+| `winCardRedeemButtonColorTop` | `string` | `'#15803d'` | Redeem button gradient top color |
+| `winCardRedeemButtonColorBottom` | `string` | `'#166534'` | Redeem button gradient bottom color |
+| `winCardRedeemButtonTextColor` | `string` | `'#ffffff'` | Redeem button text color |
+
+#### Confetti
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `confettiOnWin` | `boolean` | `true` | Show confetti on win |
+| `confettiColors` | `string[] \| null` | `null` | Array of confetti colors |
+| `confettiCount` | `number` | `40` | Number of confetti pieces |
+
+#### Theme
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `theme` | `object` | See below | Color theme overrides |
+
+#### Callbacks
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `onSpinStart` | `function` | `null` | `(winIndex) => void` |
+| `onSpinEnd` | `function` | `null` | `(prize, winIndex) => void` |
+| `onRedeem` | `function` | `null` | `(prize) => void` |
+| `onSpinLimitReached` | `function` | `null` | `(count) => void` |
+
+### Segment Object
+
+```js
+{
+  label: 'Free Gift',       // text on the wheel (required)
+  color: '#55efc4',          // segment background color (required)
+  icon:  '🎁',               // emoji/icon (optional)
+  title: 'Free Gift Voucher', // title on win card (optional, falls back to label)
+  worth: '₹299',             // "WORTH ₹299" on win card (optional)
+  code:  'FIXEDCODE',        // fixed code – overrides auto-generate (optional)
+}
+```
+
+### SpinWheel Instance Methods
+
+| Method | Description |
+|---|---|
+| `.spin(forceIndex?)` | Trigger a spin; optionally force which segment wins |
+| `.updateSegments(segments[])` | Replace all segments at runtime and re-render |
+| `.hideWinCard()` | Programmatically close the win card overlay |
+| `.updateOptions(opts)` | Update configuration options at runtime |
+| `.resetSpinCount(count?)` | Reset the spin count (default: 0) |
+| `.destroy()` | Remove all SDK-created DOM and clean up |
+
+### SpinWheel Instance Getters
+
+| Getter | Type | Description |
+|---|---|---|
+| `.lastWonPrize` | `Segment \| null` | The last prize that was won |
+| `.lastWonIndex` | `number` | The last won segment index (-1 if none) |
+| `.spinCount` | `number` | Total spins performed |
+| `.remainingSpins` | `number \| null` | Remaining spins (`null` if unlimited) |
+
+### SpinWheel Theme Defaults
+
+```js
+{
+  gold:      '#e8c547',
+  goldLight: '#f5d76e',
+  goldDark:  '#c9a227',
+  bgDark:    '#0d0d12',
+  textMuted: '#9ca3af',
+}
+```
+
+---
+
+## ScratchCard API Reference
+
+### `ScratchCard.init(options)` → `ScratchCardInstance`
+
+#### Core Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `container` | `string \| HTMLElement` | *required* | CSS selector or DOM element |
+| `prize` | `Prize` | *required* | Prize object: `{ name, icon, label }` |
+
+#### Header UI
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `headerTitle` | `string` | `'Scratch the Card...'` | Header text |
+| `headerTitleColor` | `string \| null` | `null` | Header title color |
+
+#### Instruction
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `instruction` | `string` | `'Scratch the card...'` | Instruction text |
+| `instructionColor` | `string \| null` | `null` | Instruction text color |
+
+#### Scratch Behavior
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `revealThreshold` | `number` | `55` | % scratched to auto-reveal |
+| `brushSize` | `number` | `28` | Scratch brush size in px |
+
+#### Coin / Eraser Tool
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `coinSize` | `number` | `56` | Coin cursor size in px |
+| `showCoin` | `boolean` | `true` | Show coin cursor |
+| `coinIcon` | `string` | `'$'` | Icon on coin |
+| `coinGradientStart` | `string \| null` | `null` | Coin gradient start color |
+| `coinGradientEnd` | `string \| null` | `null` | Coin gradient end color |
+
+#### Card Appearance
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `cardBackground` | `string \| null` | `null` | Card background CSS |
+| `cardShadow` | `boolean` | `true` | Enable card shadow |
+| `cardBorderRadius` | `number` | `24` | Card border radius in px |
+
+#### Scratch Zone
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `scratchZoneBackground` | `string \| null` | `null` | Scratch zone background |
+| `scratchZoneShadow` | `boolean` | `true` | Enable zone shadow |
+| `scratchZoneBorderRadius` | `number` | `20` | Zone border radius in px |
+
+#### Scratch Layer
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `scratchLayerColor` | `string` | `'rgb(150,130,180)'` | Scratch layer color |
+| `scratchLayerSparkles` | `boolean` | `true` | Show sparkles on layer |
+| `scratchLayerSparkleCount` | `number` | `40` | Number of sparkles |
+
+#### Prize Display
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `prizeTextColor` | `string \| null` | `null` | Prize label color |
+| `prizeNameColor` | `string \| null` | `null` | Prize name color |
+| `prizeIconBackground` | `string \| null` | `null` | Prize icon background |
+
+#### Gift Icon Hint
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `showGiftIcon` | `boolean` | `true` | Show gift icon hint |
+| `giftIcon` | `string` | `'🎁'` | Gift icon emoji |
+| `giftIconBackground` | `string \| null` | `null` | Gift icon background |
+
+#### Modal
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `showModal` | `boolean` | `true` | Show modal after reveal |
+| `modalTitle` | `string` | `'Congratulations!'` | Modal title |
+| `modalTitleColor` | `string \| null` | `null` | Modal title color |
+| `modalButtonText` | `string` | `'Claim your'` | Modal button text prefix |
+| `modalButtonColor` | `string \| null` | `null` | Modal button background |
+| `modalButtonTextColor` | `string \| null` | `null` | Modal button text color |
+| `modalBackdropBlur` | `boolean` | `true` | Enable backdrop blur |
+
+#### Confetti
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `confettiEnabled` | `boolean` | `true` | Enable confetti |
+| `confettiColors` | `string[] \| null` | `null` | Confetti colors array |
+| `confettiCount` | `number` | `100` | Number of confetti pieces |
+| `confettiDuration` | `number` | `5500` | Confetti duration in ms |
+
+#### Animation
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `animationType` | `string` | `'default'` | `'default'` \| `'bounce'` \| `'none'` |
+| `animationDuration` | `number` | `600` | Animation duration in ms |
+
+#### Theme
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `theme` | `object` | See below | Color theme overrides |
+
+#### Callbacks
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `onScratchStart` | `function` | `null` | `() => void` |
+| `onScratchProgress` | `function` | `null` | `(percent) => void` |
+| `onReveal` | `function` | `null` | `(prize) => void` |
+| `onClaim` | `function` | `null` | `(prize) => void` |
+
+### Prize Object
+
+```js
+{
+  name: 'iPhone 16',        // Prize name (required)
+  icon: '📱',                // Emoji/icon (optional)
+  label: 'Congratulations!', // Label above prize name (optional)
+}
+```
+
+### ScratchCard Instance Methods
+
+| Method | Description |
+|---|---|
+| `.reveal()` | Programmatically reveal the prize |
+| `.reset()` | Reset the card for replay |
+| `.hideModal()` | Hide the win modal |
+| `.showModal()` | Show the win modal |
+| `.updatePrize(prize)` | Update prize at runtime and reset card |
+| `.updateOptions(opts)` | Update configuration at runtime |
+| `.destroy()` | Remove all SDK-created DOM and clean up |
+
+### ScratchCard Instance Getters
+
+| Getter | Type | Description |
+|---|---|---|
+| `.scratchPercent` | `number` | Current scratch progress (0-100) |
+| `.hasRevealed` | `boolean` | Whether the prize has been revealed |
+| `.prize` | `Prize \| null` | Current prize object |
+
+### ScratchCard Theme Defaults
+
+```js
+{
+  purpleDark:  '#4a2c6a',
+  purpleMid:   '#6b4a8a',
+  purpleLight: '#8b6baa',
+  gold:        '#d4a84b',
+  goldLight:   '#e8c547',
+  goldDark:    '#b8923a',
+  white:       '#ffffff',
+  textDark:    '#2d2d2d',
+  textMuted:   '#6b6b6b',
+}
+```
+
+---
+
+## React Ref Methods
+
+### SpinWheelReact
+
+| Method / Getter | Description |
+|---|---|
+| `ref.current.spin(forceIndex?)` | Trigger a spin |
+| `ref.current.updateSegments(segs)` | Replace segments |
+| `ref.current.hideWinCard()` | Close win card |
+| `ref.current.updateOptions(opts)` | Update config |
+| `ref.current.resetSpinCount(count?)` | Reset spin count |
+| `ref.current.spinCount` | Current spin count |
+| `ref.current.remainingSpins` | Remaining spins |
+| `ref.current.lastWonPrize` | Last won prize |
+| `ref.current.lastWonIndex` | Last won index |
+| `ref.current.instance` | Raw SpinWheelInstance |
+
+### ScratchCardReact
+
+| Method / Getter | Description |
+|---|---|
+| `ref.current.reveal()` | Reveal prize |
+| `ref.current.reset()` | Reset card |
+| `ref.current.hideModal()` | Hide modal |
+| `ref.current.showModal()` | Show modal |
+| `ref.current.updatePrize(prize)` | Update prize |
+| `ref.current.updateOptions(opts)` | Update config |
+| `ref.current.scratchPercent` | Scratch progress |
+| `ref.current.hasRevealed` | Is revealed? |
+| `ref.current.prize` | Current prize |
+| `ref.current.instance` | Raw ScratchCardInstance |
+
+---
+
+## File Structure
+
+```
+sdk/
+├── src/
+│   ├── SpinWheel.js           ← SpinWheel Core SDK (vanilla JS)
+│   ├── SpinWheelReact.js      ← SpinWheel React wrapper (factory)
+│   ├── ScratchCard.js         ← ScratchCard Core SDK (vanilla JS)
+│   ├── ScratchCardReact.js    ← ScratchCard React wrapper (factory)
+│   ├── styles.js              ← SpinWheel styles
+│   ├── scratchStyles.js       ← ScratchCard styles
+│   ├── index.js               ← Main barrel export
+│   ├── react.js               ← React subpath entry (pre-wires factories)
+│   └── utils.js               ← Shared utilities
+├── dist/                       ← Built SDK files
+│   ├── spin-wheel-sdk.umd.js      ← UMD (browser <script>)
+│   ├── spin-wheel-sdk.umd.min.js  ← UMD minified
+│   ├── spin-wheel-sdk.esm.mjs     ← ESM (import/export)
+│   ├── spin-wheel-sdk.cjs.js      ← CommonJS (require)
+│   ├── spin-wheel-sdk.d.ts        ← TypeScript declarations (main)
+│   ├── react.esm.mjs              ← React subpath ESM
+│   ├── react.cjs.js               ← React subpath CJS
+│   └── react.d.ts                 ← TypeScript declarations (React)
+├── types/                      ← Source TypeScript declarations (copied into dist/)
+│   ├── spin-wheel-sdk.d.ts
+│   └── react.d.ts
+├── scripts/                    ← Build helpers
+│   └── copy-types.mjs
+├── demo-vanilla-combined.html  ← Combined Vanilla JS demo
+├── demo-react-combined.html    ← Combined React demo
+├── package.json
+├── CHANGELOG.md
+├── LICENSE
+└── README.md
+```
+
+---
+
+## License
+
+MIT