SDK Playground: Interactive Demo with All SDK Capabilities

[rockfridrich]

Summary

The docs playground currently only shows 3 static code examples. We need a fully interactive playground that demonstrates ALL SDK capabilities with live execution.

Current State

• Playground location: https://docs.villa.cash/playground
• Current examples: 3 (sign-in, get-profile, resolve-ens)
• Execution: Fake - just shows instructional text
• Live demo: Embeds construction.villa.cash/sdk-demo in iframe

Goals

1. Make SDK adjustable at runtime - Users should configure SDK options live
2. Demo ALL SDK capabilities - Not just auth, but ENS, avatars, nicknames, etc.
3. Real code execution - Actually run code in browser sandbox

---

Implementation Plan

Phase 1: SDK Configuration Panel (Day 1 - 2h)

Create a configuration sidebar that adjusts SDK at runtime:

// Config options to expose:
interface PlaygroundConfig {
  network: 'base' | 'base-sepolia';
  appId: string;
  debug: boolean;
  timeout: number;
}

UI Components:

• Network selector (Base Mainnet / Base Sepolia)
• App ID input
• Debug mode toggle
• Timeout slider

Phase 2: Complete Examples Library (Day 1 - 3h)

Add examples for ALL SDK exports:

Category	Examples
Auth	villa.signIn(), villa.signOut(), villa.settings(), villa.onAuthChange()
ENS	resolveEns(), reverseEns()
Avatar	getAvatarUrl(), createAvatarConfig()
Nickname	generateNickname(), validateNickname(), normalizeNickname()
Session	saveSession(), loadSession(), clearSession()
Browser	detectBrowserCapabilities(), isPasskeySupported(), getPasskeyManagerName()
Contracts	getContracts(), getNicknameResolverAddress()
Wallet	generateWallet(), encryptPrivateKey(), decryptPrivateKey()

Phase 3: Live Code Execution (Day 1 - 2h)

Options for safe browser execution:

Option A: Sandboxed iframe + postMessage (Recommended)

• Create hidden iframe with SDK loaded
• Send code via postMessage
• Receive results back
• Pros: Secure, isolated, real execution
• Cons: Slightly complex setup

Option B: Function constructor sandbox

const sandbox = {
  villa, resolveEns, getAvatarUrl, // exposed SDK
  console: { log: (msg) => addOutput(msg) }
};
const fn = new Function(...Object.keys(sandbox), code);
fn(...Object.values(sandbox));

• Pros: Simple, immediate
• Cons: Less isolated

Option C: Monaco Editor + eval (Not recommended)

• Security concerns with eval

Phase 4: Interactive Results Panel (Day 1 - 1h)

interface OutputEntry {
  type: 'log' | 'error' | 'result' | 'event';
  timestamp: number;
  content: any;
}

// Show structured output:
- Console logs with timestamps
- Error messages with stack traces  
- Return values with JSON formatting
- Auth events (success, cancel, error)
- Network requests (if debug mode)

---

File Changes

apps/developers/src/app/playground/
├── page.tsx                 # Main playground (UPDATE)
├── components/
│   ├── ConfigPanel.tsx      # SDK configuration sidebar (NEW)
│   ├── ExamplePicker.tsx    # Enhanced example selector (NEW)
│   ├── CodeRunner.tsx       # Sandboxed execution (NEW)
│   ├── OutputPanel.tsx      # Results display (NEW)
│   └── LivePreview.tsx      # Visual preview for avatars/etc (NEW)
└── examples/
    ├── index.ts             # All examples registry (NEW)
    ├── auth.ts              # Auth examples (NEW)
    ├── ens.ts               # ENS examples (NEW)
    ├── avatar.ts            # Avatar examples (NEW)
    ├── nickname.ts          # Nickname examples (NEW)
    └── browser.ts           # Browser capability examples (NEW)

---

Quick Start Tasks

Task 1: Config Panel (Start Here)

# Create the config panel component
touch apps/developers/src/app/playground/components/ConfigPanel.tsx

Task 2: Expand Examples

# Create examples registry
mkdir -p apps/developers/src/app/playground/examples

Task 3: Code Runner

# Create sandboxed runner
touch apps/developers/src/app/playground/components/CodeRunner.tsx

---

Acceptance Criteria

• Users can switch between Base and Base Sepolia
• All 30+ SDK functions have runnable examples
• Code actually executes in browser (not fake output)
• Avatar generation shows visual preview
• ENS resolution shows real results
• Auth flow works with real passkeys
• Console output is formatted and timestamped
• Mobile responsive

---

Priority

HIGH - This is the primary developer onboarding experience

Estimate

4-6 hours for full implementation

Labels

enhancement, docs, sdk, priority-high