feat: implement multiple buttons API with variants

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'packages/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: pnpm build:docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./docs/out
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

README.md

@@ -61,6 +61,33 @@ experiences.register('welcome', { ... });
 const decision = experiences.evaluate();
 ```
 
+### Event-Driven Architecture
+
+Listen to events to integrate with analytics, tracking, and custom business logic:
+
+```typescript
+// Track impressions
+experiences.on('experiences:evaluated', ({ decision, experience }) => {
+  if (decision.show && experience) {
+    analytics.track('Experience Shown', { id: experience.id });
+  }
+});
+
+// Track button clicks
+experiences.on('experiences:action', ({ experienceId, action, url }) => {
+  analytics.track('Experience Action', { experienceId, action });
+});
+
+// Track dismissals
+experiences.on('experiences:dismissed', ({ experienceId }) => {
+  analytics.track('Experience Dismissed', { experienceId });
+});
+```
+
+**Multiple listeners can react to the same event** (jstag3, GA, Segment, custom code).
+
+See the [Events Reference](https://your-docs-url/api/events) for comprehensive documentation.
+
 ## Documentation
 
 See [notes/IMPLEMENTATION_PLAN.md](notes/IMPLEMENTATION_PLAN.md) for detailed implementation guide.

biome.json

@@ -32,12 +32,17 @@
         "packages/core/src/types.ts",
         "packages/core/src/runtime.ts",
         "packages/plugins/src/types.ts",
-        "specs/**/contracts/types.ts"
+        "specs/**/contracts/types.ts",
+        "docs/**/*.tsx"
       ],
       "linter": {
         "rules": {
           "suspicious": {
-            "noExplicitAny": "off"
+            "noExplicitAny": "off",
+            "noArrayIndexKey": "off"
+          },
+          "correctness": {
+            "useExhaustiveDependencies": "off"
           }
         }
       }

docs/.gitignore

@@ -0,0 +1,21 @@
+# Next.js
+.next/
+out/
+build/
+
+# Dependencies
+node_modules/
+
+# Build outputs
+public/sdk/
+
+# Local env
+.env*.local
+
+# Debug
+npm-debug.log*
+.pnpm-debug.log*
+
+# Vercel
+.vercel
+

docs/README.md

@@ -0,0 +1,108 @@
+# Experience SDK Documentation
+
+This is the documentation site for the Experience SDK, built with [Nextra](https://nextra.site/).
+
+## Development
+
+```bash
+# From root of monorepo
+pnpm docs:dev
+```
+
+Visit http://localhost:3000
+
+## Building
+
+### Build everything (SDK + docs)
+```bash
+# From root of monorepo
+pnpm build:docs
+```
+
+### Build only docs (faster if SDK already built)
+```bash
+# From root of monorepo
+pnpm --filter docs build
+```
+
+The site will be built to `docs/out/` directory (static export).
+
+## Deployment
+
+### GitHub Pages (Automatic)
+
+The docs are automatically deployed to GitHub Pages on every push to `main` that affects:
+- `docs/**`
+- `packages/**` (SDK changes)
+- `.github/workflows/docs.yml`
+
+**Setup:**
+1. Go to repository Settings → Pages
+2. Set Source to "GitHub Actions"
+3. Push to main → site deploys automatically
+
+**URL:** `https://prosdevlab.github.io/experience-sdk/`
+
+### Vercel (Manual)
+
+1. Install Vercel CLI: `npm i -g vercel`
+2. From the `docs/` directory, run: `vercel`
+3. Follow the prompts
+4. The site will be deployed automatically
+
+The `vercel.json` config handles the monorepo build process.
+
+### Cloudflare Pages
+
+1. Connect your GitHub repository
+2. Set build command: `pnpm install && pnpm build:docs`
+3. Set output directory: `docs/out`
+4. Deploy
+
+## Manual Build & Deploy
+
+```bash
+# Build docs
+pnpm build:docs
+
+# Output is in docs/out/
+# Serve it with any static file server:
+npx serve docs/out
+```
+
+## Structure
+
+```
+docs/
+├── pages/              # MDX pages
+│   ├── index.mdx      # Homepage
+│   ├── getting-started.mdx
+│   ├── demo/          # Interactive demos
+│   │   ├── index.mdx  # Demo overview
+│   │   └── banner.mdx # Banner demo
+│   └── api/           # API reference
+├── components/         # React components
+│   ├── ExperienceDemo.tsx (old)
+│   └── BannerDemo.tsx # Banner demo component
+├── public/            # Static files
+│   └── sdk/          # SDK bundle (auto-generated)
+├── out/              # Build output (gitignored)
+├── theme.config.tsx   # Nextra theme config
+└── next.config.js     # Next.js config
+```
+
+## SDK Bundle
+
+The SDK is automatically copied to `public/sdk/` during the build process via the `prebuild` script in `package.json`. This allows:
+
+1. Script tag demos to load the SDK from `/sdk/index.global.js`
+2. Both npm and CDN usage examples
+3. Interactive demos to work without external dependencies
+
+The prebuild script runs:
+```bash
+pnpm --filter @prosdevlab/experience-sdk build && \
+  mkdir -p public/sdk && \
+  cp -r ../packages/core/dist/* public/sdk/
+```
+