chore: clean up

rm unused comments, rm env vars from example, rm redundant props, simplify to not require variant names (index order), update docs

Author: wackerow

.env.example

@@ -30,27 +30,6 @@
 NEXT_PUBLIC_MATOMO_URL=
 NEXT_PUBLIC_MATOMO_SITE_ID=
 
-# A/B Testing Configuration - Server-side A/B testing using Matomo for tracking
-# Format for variants: "name1:weight1,name2:weight2,name3:weight3"
-# Weights can be any positive numbers (don't need to sum to 100)
-# Test names should be descriptive and match Matomo experiment names
-
-# Template for new tests:
-# ABTEST_[TEST_NAME]_ENABLED=false
-# ABTEST_[TEST_NAME]_ID=[MATOMO_EXPERIMENT_ID]
-# ABTEST_[TEST_NAME]_VARIANTS="original:50,variant_b:50"
-
-# Example: Homepage Persona CTAs Test
-# ABTEST_HOMEPAGE_PERSONA_CTAS_ENABLED=false
-# ABTEST_HOMEPAGE_PERSONA_CTAS_ID=1
-# ABTEST_HOMEPAGE_PERSONA_CTAS_VARIANTS="original:50,variant_b:50"
-
-# Example: Multi-variant Wallet Layout Test  
-# ABTEST_WALLET_LAYOUT_ENABLED=false
-# ABTEST_WALLET_LAYOUT_ID=2
-# ABTEST_WALLET_LAYOUT_VARIANTS="original:40,list_view:30,carousel:30"
-
-
 # Used to avoid loading Matomo in our preview deploys
 IS_PREVIEW_DEPLOY=false
 

CLAUDE.md

@@ -201,7 +201,7 @@ The site uses a GDPR-compliant, cookie-less A/B testing system integrated with M
 ### Key Features
 
 - **Matomo API Integration** - Experiments configured in Matomo dashboard
-- **Cookie-less Tracking** - Uses deterministic IP + User-Agent fingerprinting
+- **Cookie-less Variant Persistence** - Uses deterministic IP + User-Agent fingerprinting for variant assignment
 - **Server-side Rendering** - No layout shifts, consistent variants on first load
 - **Real-time Updates** - Change weights instantly via Matomo (no deployments)
 - **Preview Mode** - Debug panel available in development and preview environments
@@ -222,14 +222,18 @@ The site uses a GDPR-compliant, cookie-less A/B testing system integrated with M
    <ABTestWrapper
      testKey="HomepageHero"  // Must match Matomo experiment name exactly
      variants={[
-       <OriginalComponent key="original" />,
-       <NewComponent key="variant" />
+       <OriginalComponent key="current-hero" />,     // Index 0: Original
+       <NewComponent key="redesigned-hero" />        // Index 1: Variation
      ]}
      fallback={<OriginalComponent />}
    />
    ```
 
-**No TypeScript changes required** - the system automatically fetches configuration from Matomo.
+**Important**:
+- Variants matched by **array index**, not names
+- Array order must match Matomo experiment order exactly
+- JSX `key` props become debug panel labels: `"redesigned-hero"` → `"Redesigned Hero"`
+- No TypeScript changes required - system fetches configuration from Matomo
 
 ### Architecture
 

app/[locale]/stablecoins/page.tsx

@@ -594,7 +594,7 @@ async function Page({ params }: { params: Promise<{ locale: Lang }> }) {
             <ABTestWrapper
               testKey="AppTest"
               variants={[
-                <div key="original" className="flex flex-wrap gap-4">
+                <div key="two-buttons" className="flex flex-wrap gap-4">
                   <ButtonLink href="/dapps/">
                     {t("page-stablecoins-explore-dapps")}
                   </ButtonLink>
@@ -607,7 +607,7 @@ async function Page({ params }: { params: Promise<{ locale: Lang }> }) {
                     {t("page-stablecoins-more-defi-button")}
                   </ButtonLink>
                 </div>,
-                <div key="Variation1" className="flex flex-wrap gap-4">
+                <div key="single-button" className="flex flex-wrap gap-4">
                   <ButtonLink href="/dapps/">
                     {t("page-stablecoins-explore-apps")}
                   </ButtonLink>

docs/ab-testing.md

@@ -55,15 +55,21 @@ export default function MyPage() {
       <ABTestWrapper
         testKey="HomepageHero" // Must match your Matomo experiment name exactly
         variants={[
-          <OriginalComponent key="original" />, // Index 0: Original/existing variant
-          <NewDesignComponent key="newdesign" />, // Index 1: First test variation
+          <OriginalComponent key="current-design" />, // Index 0: Original (matches Matomo order)
+          <NewDesignComponent key="hero-redesign" />, // Index 1: Variation (matches Matomo order)
         ]}
       />
     </div>
   )
 }
 ```
 
+**Important Notes:**
+
+- Variants are matched by **array index**, not by name
+- Array order must match the exact order of variations in your Matomo experiment
+- JSX `key` props serve as array keys, and human-readable labels in the debug panel (parsed from kebab-case to Title Case)
+
 ### 4. Experiment Activation
 
 The experiment will automatically start running when:
@@ -73,6 +79,7 @@ The experiment will automatically start running when:
 3. **Matomo detects the experiment** and begins tracking
 
 **Manual Control:**
+
 - Use the **Schedule** settings in Matomo to control start/end dates
 - Experiments respect their configured schedule automatically
 - You can pause/resume experiments anytime in the Matomo dashboard
@@ -82,24 +89,28 @@ The experiment will automatically start running when:
 Support for 3+ variants:
 
 ```tsx
-// Matomo experiment with:
-// - Original: 40% (implicit)
-// - ListLayout: 30%
-// - GridLayout: 20%
-// - CarouselLayout: 10%
+// Matomo experiment configured with variations in this exact order:
+// Index 0: Original (implicit) - 40% weight
+// Index 1: List Layout - 30% weight
+// Index 2: Grid Layout - 20% weight
+// Index 3: Carousel Layout - 10% weight
 
 <ABTestWrapper
   testKey="WalletLayout"
   variants={[
-    <OriginalLayout />, // Index 0: Original (40% weight)
-    <ListLayout />, // Index 1: ListLayout (30% weight)
-    <GridLayout />, // Index 2: GridLayout (20% weight)
-    <CarouselLayout />, // Index 3: CarouselLayout (10% weight)
+    <OriginalLayout key="original-layout" />, // Index 0
+    <ListLayout key="list-layout" />, // Index 1
+    <GridLayout key="grid-layout" />, // Index 2
+    <CarouselLayout key="carousel-layout" />, // Index 3
   ]}
 />
 ```
 
-**Important**: Variant array order must match the order of variations in your Matomo experiment.
+**Important**:
+
+- Variant array order must exactly **match the order in your Matomo experiment**
+- Assignment is by index (0, 1, 2, 3...), not by name matching
+- Debug panel shows formatted key names: `"list-layout"` → `"List Layout"`
 
 ## How It Works
 
@@ -169,6 +180,8 @@ IS_PREVIEW_DEPLOY=false
 
 - Keep variants as similar as possible (same props, structure)
 - Always provide a meaningful fallback component
+- Use descriptive kebab-case keys: `key="simplified-checkout"` becomes `"Simplified Checkout"` in debug panel
+- Ensure variant array order matches Matomo experiment order exactly
 - Test all variants in Storybook before deploying
 
 ### Testing Strategy
@@ -230,10 +243,10 @@ The panel helps verify your test is working correctly before production deployme
 ### Core Files
 
 - `app/api/ab-config/route.ts` - Matomo API integration
-- `src/lib/ab-testing/config.ts` - Configuration management and caching
-- `src/lib/ab-testing/server.ts` - Assignment logic and fingerprinting
+- `src/lib/ab-testing/server.ts` - Assignment logic and fingerprinting (index-based)
 - `src/components/AB/TestWrapper.tsx` - Main React component
 - `src/components/AB/TestDebugPanel.tsx` - Development debug interface
+- `src/components/AB/ClientABTestWrapper.tsx` - Client-side rendering with localStorage overrides
 
 ### Data Flow
 

src/components/AB/TestWrapper.tsx

@@ -6,11 +6,7 @@ import { ClientABTestWrapper } from "./ClientABTestWrapper"
 import { ABTestDebugPanel } from "./TestDebugPanel"
 import { ABTestTracker } from "./TestTracker"
 
-import {
-  getABTestAssignment,
-  getABTestConfigs,
-  getVariantIndex,
-} from "@/lib/ab-testing/server"
+import { getABTestAssignment } from "@/lib/ab-testing/server"
 import { ABTestVariants } from "@/lib/ab-testing/types"
 
 type ABTestWrapperProps = {
@@ -25,18 +21,28 @@ const ABTestWrapper = async ({
   fallback,
 }: ABTestWrapperProps) => {
   try {
-    // Get deterministic assignment and configs
-    const [assignment, configs] = await Promise.all([
-      getABTestAssignment(testKey),
-      getABTestConfigs(),
-    ])
+    // Get deterministic assignment
+    const assignment = await getABTestAssignment(testKey)
 
     if (!assignment) throw new Error("No AB test assignment found")
 
-    // Find the variant index based on the assignment
-    const variantIndex = getVariantIndex(assignment.variant, configs, testKey)
-    const availableVariants =
-      configs[testKey]?.variants.map((v) => v.name) || []
+    // Use assignment's variant index directly
+    const variantIndex = assignment.variantIndex
+
+    // Extract labels from React element keys or fall back to defaults
+    const availableVariants = variants.map((variant, i) => {
+      if (
+        variant &&
+        typeof variant === "object" &&
+        "key" in variant &&
+        variant.key
+      ) {
+        return String(variant.key)
+          .replace(/-/g, " ")
+          .replace(/\b\w/g, (l) => l.toUpperCase())
+      }
+      return `Variant ${i}`
+    })
 
     return (
       <>

src/lib/ab-testing/index.ts

@@ -2,11 +2,7 @@
 export type { ABTestAssignment, ABTestConfig, ABTestVariants } from "./types"
 
 // Server utilities (only import these in server components)
-export {
-  getABTestAssignment,
-  getABTestConfigs,
-  getVariantIndex,
-} from "./server"
+export { getABTestAssignment, getABTestConfigs } from "./server"
 
 // Note: Server actions are exported from ./actions, not here
 // This prevents client components from accidentally importing server-only code

src/lib/ab-testing/server.ts

@@ -33,42 +33,30 @@ export const getABTestAssignment = async (
     headers.get("x-forwarded-for") || headers.get("x-real-ip") || "unknown"
   const fingerprint = `${forwardedFor}-${userAgent}`
 
-  const variant = assignVariantDeterministic(testConfig, fingerprint)
+  const variantIndex = assignVariantIndexDeterministic(testConfig, fingerprint)
+  const variant = testConfig.variants[variantIndex]
 
   return {
     experimentId: testConfig.id,
     experimentName: testConfig.name || testKey,
     variant: variant.name,
+    variantIndex,
     assignedAt: Date.now(),
   }
 }
 
-export const getVariantIndex = (
-  variantName: string,
-  configs: Record<string, ABTestConfig>,
-  testKey: string
-): number => {
-  const testConfig = configs[testKey]
-  if (!testConfig) return 0
-
-  const variantIndex = testConfig.variants.findIndex(
-    (v) => v.name === variantName
-  )
-  return variantIndex >= 0 ? variantIndex : 0
-}
-
 // Deterministic assignment based on user fingerprint (cookie-less)
-const assignVariantDeterministic = (
+const assignVariantIndexDeterministic = (
   config: ABTestConfig,
   fingerprint: string
-) => {
+): number => {
   const totalWeight = config.variants.reduce(
     (sum, variant) => sum + variant.weight,
     0
   )
 
   // Handle case where total weight is 0
-  if (totalWeight === 0) return config.variants[0]
+  if (totalWeight === 0) return 0
 
   // Use a better hash function for more uniform distribution
   // This is a simple implementation of djb2 hash algorithm
@@ -82,12 +70,12 @@ const assignVariantDeterministic = (
   const weighted = normalized * totalWeight
 
   let cumulativeWeight = 0
-  for (const variant of config.variants) {
-    cumulativeWeight += variant.weight
+  for (let i = 0; i < config.variants.length; i++) {
+    cumulativeWeight += config.variants[i].weight
     if (weighted <= cumulativeWeight) {
-      return variant
+      return i
     }
   }
 
-  return config.variants[0]
+  return 0
 }

src/lib/ab-testing/types.ts

@@ -14,6 +14,7 @@ export type ABTestAssignment = {
   experimentId: string
   experimentName: string
   variant: string
+  variantIndex: number
   assignedAt: number
 }