@limeade-labs/sparkui 1.0.0

package/docs/mcp-setup.md

@@ -0,0 +1,195 @@
+# MCP Setup
+
+Use SparkUI from AI clients like Claude Desktop, Cursor, and Windsurf via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
+
+## What is MCP?
+
+MCP (Model Context Protocol) is an open standard that lets AI applications connect to external tools and data sources. Instead of writing custom integrations, any MCP-compatible client can use SparkUI tools through a standard protocol.
+
+The SparkUI MCP server exposes tools like `sparkui_push` and `sparkui_compose` that AI clients can call to create ephemeral web pages.
+
+## Prerequisites
+
+1. SparkUI server running (see [Getting Started](./getting-started.md))
+2. Your push token from `.env`
+3. An MCP-compatible client (Claude Desktop, Cursor, Windsurf, Cline, etc.)
+
+## Install the MCP Server
+
+```bash
+cd mcp-server
+npm install
+```
+
+The MCP server is a lightweight Node.js process that communicates with your SparkUI server over HTTP.
+
+## Claude Desktop Setup
+
+Edit your Claude Desktop config file:
+
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "sparkui": {
+      "command": "node",
+      "args": ["/absolute/path/to/sparkui/mcp-server/index.js"],
+      "env": {
+        "SPARKUI_URL": "http://localhost:3457",
+        "SPARKUI_TOKEN": "your-push-token"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving. You should see "sparkui" in the MCP tools list (🔨 icon).
+
+> **Tip:** Use an absolute path for the `args` value. Relative paths may not resolve correctly.
+
+## Cursor Setup
+
+Add to `.cursor/mcp.json` in your project root (or global config):
+
+```json
+{
+  "mcpServers": {
+    "sparkui": {
+      "command": "node",
+      "args": ["/absolute/path/to/sparkui/mcp-server/index.js"],
+      "env": {
+        "SPARKUI_URL": "http://localhost:3457",
+        "SPARKUI_TOKEN": "your-push-token"
+      }
+    }
+  }
+}
+```
+
+## Windsurf Setup
+
+Add to `.windsurf/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "sparkui": {
+      "command": "node",
+      "args": ["/absolute/path/to/sparkui/mcp-server/index.js"],
+      "env": {
+        "SPARKUI_URL": "http://localhost:3457",
+        "SPARKUI_TOKEN": "your-push-token"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SPARKUI_URL` | No | `http://localhost:3457` | Base URL of the SparkUI server |
+| `SPARKUI_TOKEN` | Yes | — | Push token for API authentication |
+
+## Available MCP Tools
+
+### `sparkui_list_templates`
+
+List available page templates.
+
+**Parameters:** None
+
+**Returns:**
+
+```json
+{ "templates": ["macro-tracker", "ws-test", "feedback-form", "checkout", "workout-timer"] }
+```
+
+### `sparkui_list_components`
+
+List available components for page composition.
+
+**Parameters:** None
+
+**Returns:**
+
+```json
+{ "components": ["header", "button", "timer", "checklist", "progress", "stats", "form", "tabs"] }
+```
+
+### `sparkui_push`
+
+Create a page from a template.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `template` | string | Yes | Template name |
+| `data` | object | Yes | Template data |
+| `ttl` | number | No | Time-to-live in seconds |
+| `og` | object | No | Open Graph overrides (`title`, `description`, `image`) |
+
+### `sparkui_compose`
+
+Compose a page from individual components.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | Yes | Page title |
+| `sections` | array | Yes | Array of `{ type, config }` component sections |
+| `ttl` | number | No | Time-to-live in seconds |
+
+### `sparkui_page_status`
+
+Check if a page is still active.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | Yes | Page UUID |
+
+## Example Usage
+
+Once configured, you can ask your AI client naturally:
+
+> "Create a feedback form asking about the new feature"
+
+The AI client will call `sparkui_push` with the feedback-form template and return a URL you can open.
+
+> "Make a dashboard showing my project stats: 42 tasks done, 8 in progress, 3 blocked"
+
+The AI will use `sparkui_compose` with header, stats, and progress components.
+
+> "Build me a workout timer: 3 rounds of push-ups, squats, and planks with 60-second rest"
+
+The AI calls `sparkui_push` with the workout-timer template.
+
+## Architecture
+
+```
+Claude Desktop / Cursor / Windsurf
+        ↓ (MCP stdio)
+   SparkUI MCP Server (Node.js)
+        ↓ (HTTP)
+   SparkUI Server (localhost:3457)
+        ↓
+   Ephemeral web pages
+```
+
+The MCP server is a thin client — it translates MCP tool calls into SparkUI HTTP API requests. It doesn't import SparkUI internals or require being co-located with the SparkUI server.
+
+## Troubleshooting
+
+**"Tool not found" in Claude Desktop:**
+- Ensure you restarted Claude Desktop after editing the config
+- Check that the path to `index.js` is absolute and correct
+- Verify the MCP server starts: `node /path/to/mcp-server/index.js` (it should wait for stdin)
+
+**"SparkUI API error: 401":**
+- Your `SPARKUI_TOKEN` doesn't match the `PUSH_TOKEN` in your SparkUI `.env`
+- Check for trailing whitespace in the token
+
+**"Connection refused":**
+- SparkUI server isn't running — start it with `sparkui start`
+- Check that `SPARKUI_URL` matches your server's actual port

package/docs/openclaw-setup.md

@@ -0,0 +1,177 @@
+# OpenClaw Setup
+
+Integrate SparkUI as an [OpenClaw](https://github.com/openclaw/openclaw) agent skill so your AI agent can automatically generate interactive web pages during conversations.
+
+## What is OpenClaw?
+
+OpenClaw is an AI agent runtime that connects language models to tools, channels (Slack, Discord, Telegram), and external services. Skills are modular capabilities the agent can invoke — SparkUI is one such skill.
+
+When SparkUI is installed as a skill, the agent can detect when a visual UI would be better than text (dashboards, forms, trackers) and automatically generate a page without being explicitly asked.
+
+## Install SparkUI as an OpenClaw Skill
+
+### 1. Clone SparkUI into your skills directory
+
+```bash
+cd ~/your-openclaw-workspace/skills/
+git clone https://github.com/Limeade-Labs/sparkui.git
+```
+
+Or symlink if SparkUI is already installed elsewhere:
+
+```bash
+ln -s /path/to/sparkui ~/your-openclaw-workspace/skills/sparkui
+```
+
+### 2. Verify the SKILL.md
+
+SparkUI includes a `SKILL.md` file that tells the agent how to use it. The key sections are:
+
+- **When to Use** — triggers (dashboards, trackers, forms, rich content)
+- **Server Location** — directory, port, config file location
+- **Step-by-step instructions** — check server, get token, push content
+- **Available templates** — template names and data shapes
+- **Composable components** — component types and configs
+
+The agent reads this file automatically when it determines SparkUI is relevant to the task.
+
+### 3. Configure Environment
+
+Ensure the SparkUI server is accessible from the OpenClaw host. The `.env` file should include:
+
+```bash
+PUSH_TOKEN=spk_your_token_here
+SPARKUI_PORT=3457
+SPARKUI_BASE_URL=http://localhost:3457
+
+# For round-trip event callbacks to OpenClaw
+OPENCLAW_HOOKS_URL=http://127.0.0.1:18789/hooks/agent
+OPENCLAW_HOOKS_TOKEN=your_openclaw_hooks_token
+```
+
+### 4. Start the SparkUI Server
+
+```bash
+cd /path/to/sparkui
+node server.js &
+```
+
+Or use the CLI:
+
+```bash
+sparkui start
+```
+
+## How the Agent Uses It
+
+Once configured, the agent automatically detects opportunities to use SparkUI:
+
+1. **Agent reads SKILL.md** — on startup or when a relevant task is detected
+2. **Agent checks server health** — `curl http://localhost:3457/`
+3. **Agent loads push token** — `source /path/to/sparkui/.env`
+4. **Agent pushes a page** — via `curl` to the push or compose API
+5. **Agent shares the URL** — sends the `fullUrl` to the user in chat
+
+The agent decides when to use SparkUI based on the "When to Use" section in SKILL.md:
+
+- ✅ Dashboards, nutrition trackers, fitness stats
+- ✅ Data displays, tables, comparisons
+- ✅ Interactive forms, feedback collection
+- ✅ Anything with progress bars, colors, layouts
+- ❌ Simple text answers, yes/no questions, quick lists
+
+## Example: Macro Tracking Flow
+
+Here's how the agent handles a nutrition tracking request end-to-end:
+
+**User says:** "Log my lunch — chicken salad, 480 cal, 35g protein, 20g fat, 15g carbs"
+
+**Agent does:**
+
+1. Updates the nutrition spreadsheet with the new meal
+2. Reads today's totals from the sheet
+3. Pushes a macro-tracker page:
+
+```bash
+curl -s -X POST http://localhost:3457/api/push \
+  -H "Authorization: Bearer $PUSH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "template": "macro-tracker",
+    "data": {
+      "date": "2026-03-14",
+      "calories": {"current": 1250, "target": 1900},
+      "protein": {"current": 62, "target": 86},
+      "fat": {"current": 45, "target": 95},
+      "carbs": {"current": 15, "target": 25},
+      "meals": [
+        {"name": "Eggs & bacon", "calories": 450, "time": "6:30 AM"},
+        {"name": "Chicken salad", "calories": 480, "time": "12:00 PM"}
+      ]
+    },
+    "ttl": 7200
+  }'
+```
+
+4. Shares the link: "Logged! Here's your updated dashboard: http://..."
+
+## Round-Trip Events (OpenClaw Callbacks)
+
+SparkUI can forward user interactions back to the agent via OpenClaw's webhook system. This closes the loop: **agent pushes page → user interacts → agent gets notified**.
+
+### Enable OpenClaw Forwarding
+
+Add `openclaw` config when pushing a page:
+
+```json
+{
+  "template": "feedback-form",
+  "data": { "title": "Quick Feedback" },
+  "openclaw": {
+    "enabled": true,
+    "channel": "slack",
+    "to": "C0AKMF5E0KD",
+    "eventTypes": ["completion"]
+  }
+}
+```
+
+### Config Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | boolean | Enable event forwarding |
+| `channel` | string | Delivery channel (default: `"slack"`) |
+| `to` | string | Target channel/user ID |
+| `eventTypes` | string[] | Events to forward: `["completion"]`, `["event"]`, or both |
+| `sessionKey` | string | Optional session key for routing |
+
+### How It Works
+
+1. Agent pushes a page with `openclaw` config
+2. User opens the page and interacts (fills form, clicks buttons)
+3. Browser sends events via WebSocket to SparkUI server
+4. SparkUI forwards matching events to OpenClaw's `/hooks/agent` endpoint
+5. OpenClaw delivers the message to the specified channel
+6. Agent receives the notification and can respond
+
+### Use Cases
+
+- **Feedback forms** — get notified when user submits a rating
+- **Approval workflows** — user clicks approve/reject buttons
+- **Data collection** — form submissions with structured data
+- **Checklist completion** — notified when all items are checked
+
+## SKILL.md Reference
+
+The full `SKILL.md` is located at the root of the SparkUI directory. It contains:
+
+- Server location and configuration details
+- Step-by-step instructions for the agent
+- Template data schemas
+- Component reference
+- OpenClaw round-trip configuration
+
+The agent reads this file automatically — you don't need to configure it separately.
+
+> **Tip:** If you modify the SKILL.md (e.g., to add custom templates or change defaults), the agent will pick up the changes on its next invocation.

package/docs/templates.md

@@ -0,0 +1,289 @@
+# Templates
+
+SparkUI includes 5 built-in templates for common use cases. Each generates a complete, interactive HTML page with dark theme, responsive layout, and WebSocket connectivity.
+
+Use templates via `POST /api/push` with a `template` name and `data` object.
+
+---
+
+## macro-tracker
+
+Daily nutrition and macro tracking dashboard with animated progress bars, macro cards, and a meal log.
+
+### Data Schema
+
+```typescript
+interface MacroTrackerData {
+  date: string;                    // e.g. "2026-03-14"
+  calories: { current: number; target: number };
+  protein: { current: number; target: number };
+  fat: { current: number; target: number };
+  carbs: { current: number; target: number };
+  meals?: Array<{
+    name: string;                  // e.g. "Grilled chicken salad"
+    calories: number;
+    time: string;                  // e.g. "12:00 PM"
+  }>;
+}
+```
+
+### Example
+
+```json
+{
+  "template": "macro-tracker",
+  "data": {
+    "date": "2026-03-14",
+    "calories": { "current": 1250, "target": 1900 },
+    "protein": { "current": 62, "target": 86 },
+    "fat": { "current": 45, "target": 95 },
+    "carbs": { "current": 15, "target": 25 },
+    "meals": [
+      { "name": "Eggs & bacon", "calories": 450, "time": "6:30 AM" },
+      { "name": "Grilled chicken salad", "calories": 480, "time": "12:00 PM" },
+      { "name": "Greek yogurt with almonds", "calories": 320, "time": "3:00 PM" }
+    ]
+  },
+  "ttl": 7200
+}
+```
+
+### Features
+
+- Animated progress bars with percentage labels
+- Color-coded macro cards (Calories, Protein, Fat, Carbs)
+- Meal log with times and calorie counts
+- Auto-refreshes every 30 seconds
+- Over-target warnings
+
+> **Screenshot:** [screenshots/macro-tracker.png](../screenshots/macro-tracker.png)
+
+---
+
+## checkout
+
+Stripe-inspired checkout page with product display, quantity selector, promo code field, and payment form. **Demo only — no real payment processing.**
+
+### Data Schema
+
+```typescript
+interface CheckoutData {
+  product: {
+    name: string;                  // Product name
+    description: string;           // Short description
+    price: number;                 // Unit price
+    image?: string;                // Emoji (e.g. "⚡") or URL
+    imageUrl?: string;             // Product image URL (overrides image)
+  };
+  shipping?: number;               // Shipping cost (default: 0)
+  tax?: number;                    // Tax amount (default: 0)
+  currency?: string;               // Currency code (default: "USD")
+}
+```
+
+### Example
+
+```json
+{
+  "template": "checkout",
+  "data": {
+    "product": {
+      "name": "SparkUI Pro",
+      "description": "Unlimited ephemeral UIs for your agent",
+      "price": 29.99,
+      "image": "⚡"
+    },
+    "shipping": 0,
+    "tax": 2.40,
+    "currency": "USD"
+  }
+}
+```
+
+### Features
+
+- "DEMO MODE" banner (no real charges)
+- Quantity selector with live price updates
+- Promo code input
+- Simulated payment form (card number, expiry, CVC)
+- Order summary with subtotal, shipping, tax, and total
+- Sends `completion` event with order data on "Pay" click
+
+> **Screenshot:** [screenshots/checkout.png](../screenshots/checkout.png)
+
+---
+
+## workout-timer
+
+Fitness-app-quality workout page with exercise rounds, rest timer, warmup/cooldown checklists, and progress tracking.
+
+### Data Schema
+
+```typescript
+interface WorkoutTimerData {
+  title: string;                   // Workout name
+  subtitle?: string;               // e.g. "Day 3 — Push"
+  warmup?: Array<{ text: string }>;
+  exercises: Array<{
+    name: string;                  // Exercise name
+    reps: string;                  // e.g. "12 reps" or "30 sec"
+    notes?: string;                // Form tips, etc.
+  }>;
+  rounds?: number;                 // Number of rounds (default: 3)
+  restSeconds?: number;            // Rest between rounds (default: 60)
+  cooldown?: Array<{ text: string }>;
+  estimatedMinutes?: number;
+  estimatedCalories?: number;
+}
+```
+
+### Example
+
+```json
+{
+  "template": "workout-timer",
+  "data": {
+    "title": "Upper Body Blast",
+    "subtitle": "Day 1 — Push",
+    "warmup": [
+      { "text": "Arm circles — 30 sec" },
+      { "text": "Band pull-aparts — 15 reps" }
+    ],
+    "exercises": [
+      { "name": "Push-ups", "reps": "15 reps", "notes": "Full range of motion" },
+      { "name": "Dumbbell press", "reps": "12 reps", "notes": "Slow negatives" },
+      { "name": "Lateral raises", "reps": "12 reps" }
+    ],
+    "rounds": 3,
+    "restSeconds": 60,
+    "cooldown": [
+      { "text": "Chest stretch — 30 sec each side" },
+      { "text": "Shoulder stretch — 30 sec each side" }
+    ],
+    "estimatedMinutes": 35,
+    "estimatedCalories": 280
+  }
+}
+```
+
+### Features
+
+- Stats bar: rounds, exercises, estimated time and calories
+- Interactive warmup/cooldown checklists
+- Round tracker with exercise completion
+- Built-in rest timer with start/skip controls
+- Progress tracking across all rounds
+- Sends `completion` event when workout finishes
+
+> **Screenshot:** [screenshots/workout-timer.png](../screenshots/workout-timer.png)
+
+---
+
+## feedback-form
+
+Simple feedback form with star rating, text input, and optional extra questions. Sends completion event with all form data.
+
+### Data Schema
+
+```typescript
+interface FeedbackFormData {
+  title?: string;                  // Form title (default: "Feedback")
+  subtitle?: string;               // Subtitle text
+  questions?: string[];            // Optional extra text input fields
+}
+```
+
+### Example
+
+```json
+{
+  "template": "feedback-form",
+  "data": {
+    "title": "How was your experience?",
+    "subtitle": "We'd love to hear from you",
+    "questions": [
+      "What did you like most?",
+      "What could be improved?"
+    ]
+  }
+}
+```
+
+### Features
+
+- 5-star rating selector
+- Free-text feedback textarea
+- Optional extra question fields
+- Success animation on submit
+- Sends `completion` event with `{ rating, feedback, ...extraFields }`
+
+> **Screenshot:** [screenshots/feedback-form.png](../screenshots/feedback-form.png)
+
+---
+
+## ws-test
+
+WebSocket connectivity test page for debugging and development. Tests all WS bridge features.
+
+### Data Schema
+
+```typescript
+interface WsTestData {
+  // No required data — this template works with defaults
+}
+```
+
+### Example
+
+```json
+{
+  "template": "ws-test",
+  "data": {}
+}
+```
+
+### Features
+
+- Live connection status indicator
+- Send click events and custom events
+- Test form that sends completion events
+- Real-time message log showing all WebSocket traffic
+- Useful for verifying WebSocket connectivity and event forwarding
+
+---
+
+## Using Templates
+
+### Push a template page
+
+```bash
+curl -X POST http://localhost:3457/api/push \
+  -H "Authorization: Bearer $PUSH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "template": "TEMPLATE_NAME",
+    "data": { ... },
+    "ttl": 3600
+  }'
+```
+
+### Update a template page
+
+```bash
+curl -X PATCH http://localhost:3457/api/pages/PAGE_ID \
+  -H "Authorization: Bearer $PUSH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "data": { ... }
+  }'
+```
+
+When updating, you can just send `data` — SparkUI re-renders using the page's original template.
+
+### List available templates
+
+```bash
+curl http://localhost:3457/ | jq .templates
+```
+
+> **Tip:** For custom layouts that don't fit a template, use the [compose API](./components.md) to build pages from individual components.