@limeade-labs/sparkui 1.0.0

package/.env.example

@@ -0,0 +1,9 @@
+# SparkUI Configuration
+SPARKUI_PORT=3457
+PUSH_TOKEN=your-random-token-here
+SPARKUI_BASE_URL=http://localhost:3457
+
+# OpenClaw Webhook Integration (optional)
+# Forward page events (completions, form submissions) to OpenClaw
+OPENCLAW_HOOKS_URL=https://your-openclaw-instance/hooks
+OPENCLAW_HOOKS_TOKEN=your-openclaw-hooks-token

package/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing to SparkUI
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Prerequisites
+
+- Node.js 18+
+- npm or yarn
+
+## Setup
+
+```bash
+git clone https://github.com/limeade-labs/sparkui.git
+cd sparkui
+npm install
+cp .env.example .env
+# Edit .env — set SPARKUI_PUSH_TOKEN to any random string
+npm start
+```
+
+Server runs at `http://localhost:3457`. Test with:
+
+```bash
+curl http://localhost:3457/
+# {"status":"ok","templates":["macro-tracker","checkout",...]}
+```
+
+## Adding a Template
+
+1. Create `templates/your-template.js`
+2. Export a `render(data)` function that returns an HTML string
+3. Use `require('./base').base()` for the page shell (dark theme, WS client, OG tags)
+4. Register in `lib/templates.js`
+
+Look at `templates/checkout.js` for a good example.
+
+## Adding a Component
+
+1. Add your function to `lib/components.js`
+2. Components return HTML strings (inline styles, no external deps)
+3. For interactivity, use inline `<script>` blocks
+4. WebSocket events: use `window.sparkui.send({type, ...data})`
+5. Export from the `compose` function's component map
+
+## Code Style
+
+- Standard JS (semicolons, single quotes)
+- No external CSS frameworks — inline styles only
+- Dark theme: background `#0a0a0a`, cards `#1a1a1a`, text `#e0e0e0`
+- Mobile-first responsive design
+- Zero external runtime dependencies in generated HTML
+
+## Pull Requests
+
+1. Fork the repo
+2. Create a feature branch (`git checkout -b feat/my-feature`)
+3. Make your changes
+4. Test locally (push a page, verify it renders)
+5. Submit a PR with a clear description
+
+## Questions?
+
+Open an issue or reach out to the maintainers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Limeade Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# ⚡ SparkUI
+
+**Ephemeral interactive UIs for AI agents.** Generate rich web pages from chat — no app install required.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/sparkui.svg)](https://www.npmjs.com/package/sparkui)
+
+---
+
+## What is SparkUI?
+
+SparkUI lets AI agents generate interactive web UIs on demand. Instead of walls of text, your agent creates a polished, ephemeral web page and shares a link. Users click, interact, and the results flow back to the agent via WebSocket. Pages self-destruct after a configurable TTL.
+
+- 🎯 **No app install** — just a URL that works in any browser
+- ⏱️ **Ephemeral** — pages auto-expire (default 1 hour)
+- 🔄 **Bidirectional** — user actions flow back to the agent via WebSocket
+- 🧩 **Composable** — 15 components you can mix and match
+- 📱 **Mobile-first** — designed for phones, works everywhere
+- 🔌 **MCP compatible** — works with Claude Desktop, Cursor, Windsurf
+- 🌙 **Dark theme** — easy on the eyes, polished look
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/limeade-labs/sparkui.git
+cd sparkui
+npm install
+
+# Configure
+cp .env.example .env
+# Edit .env — set your PUSH_TOKEN
+
+# Run
+npm start
+# Server running at http://localhost:3457
+```
+
+## Push a Page
+
+```bash
+curl -X POST http://localhost:3457/api/push \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "template": "checkout",
+    "data": {
+      "product": {
+        "name": "SparkUI Pro",
+        "description": "Unlimited ephemeral UIs",
+        "price": 29.99,
+        "image": "⚡"
+      }
+    }
+  }'
+```
+
+Returns:
+```json
+{
+  "id": "abc123",
+  "url": "/s/abc123",
+  "fullUrl": "http://localhost:3457/s/abc123",
+  "expiresAt": "2026-03-14T01:00:00.000Z"
+}
+```
+
+## Built-in Templates
+
+<p align="center">
+  <img src="screenshots/macro-tracker.png" width="200" alt="Macro Tracker" />
+  <img src="screenshots/checkout.png" width="200" alt="Checkout" />
+  <img src="screenshots/workout-timer.png" width="200" alt="Workout Timer" />
+  <img src="screenshots/feedback-form.png" width="200" alt="Feedback Form" />
+</p>
+
+| Template | Description |
+|----------|-------------|
+| `macro-tracker` | Daily nutrition/macro tracking with progress bars |
+| `checkout` | Stripe-like checkout flow with quantity, promo codes, payment |
+| `workout-timer` | Exercise routine with rounds, rest timer, checklists |
+| `feedback-form` | Multi-field form with star ratings and text inputs |
+| `ws-test` | WebSocket connectivity test page |
+
+## Compose Custom Pages
+
+Don't want a template? Compose pages from individual components:
+
+```bash
+curl -X POST http://localhost:3457/api/compose \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Team Lunch Poll",
+    "sections": [
+      {
+        "type": "header",
+        "config": { "title": "Where should we eat?", "subtitle": "Vote by noon", "icon": "🍕" }
+      },
+      {
+        "type": "checklist",
+        "config": {
+          "items": ["Chipotle", "Chick-fil-A", "Thai place on Main St"],
+          "allowAdd": true
+        }
+      },
+      {
+        "type": "button",
+        "config": { "text": "Submit Vote", "style": "primary", "emitEvent": "vote_submitted" }
+      }
+    ]
+  }'
+```
+
+## Components
+
+| Component | Description | Key Config |
+|-----------|-------------|------------|
+| `header` | Title, subtitle, icon, badge | `title`, `subtitle`, `icon` |
+| `button` | Action button with event emission | `text`, `style`, `emitEvent` |
+| `timer` | Countdown, stopwatch, or interval timer | `mode`, `seconds`, `intervals` |
+| `checklist` | Tappable checklist with progress bar | `items`, `allowAdd` |
+| `progress` | Single or multi-segment progress bars | `segments`, `value`, `max` |
+| `stats` | Grid of stat cards with trends | `items: [{label, value, icon}]` |
+| `form` | Text, number, select, textarea, star ratings | `fields`, `submitText` |
+| `tabs` | Switchable content panels | `tabs: [{label, content}]` |
+
+All components emit events via WebSocket. Dark theme. Responsive. Zero external dependencies.
+
+## MCP Server
+
+Use SparkUI from Claude Desktop, Cursor, or Windsurf via the [MCP server](./mcp-server/README.md):
+
+```json
+{
+  "mcpServers": {
+    "sparkui": {
+      "command": "node",
+      "args": ["./mcp-server/index.js"],
+      "env": {
+        "SPARKUI_URL": "http://localhost:3457",
+        "SPARKUI_TOKEN": "your-push-token"
+      }
+    }
+  }
+}
+```
+
+## Page Management API
+
+```bash
+# List active pages
+GET /api/pages
+
+# Page details (includes view count)
+GET /api/pages/:id
+
+# Update page data or extend TTL
+PATCH /api/pages/:id
+
+# Delete a page
+DELETE /api/pages/:id
+```
+
+All endpoints require `Authorization: Bearer <token>`.
+
+## Architecture
+
+```
+┌─────────┐     POST /api/push     ┌──────────────┐     GET /s/:id     ┌─────────┐
+│  Agent   │ ──────────────────────▶│  SparkUI     │◀────────────────── │ Browser │
+│ (AI/MCP) │                        │  Server      │ ──────────────────▶│  (User) │
+│          │◀── WebSocket ──────────│  :3457       │──── WebSocket ────▶│         │
+└─────────┘   completion events     └──────────────┘   user actions     └─────────┘
+```
+
+**Flow:**
+1. Agent pushes a page (template or composed)
+2. Server generates HTML, stores in memory, returns URL
+3. User opens URL in any browser
+4. User interacts (checks items, fills forms, clicks buttons)
+5. Actions flow back to the agent via WebSocket
+6. Page auto-expires after TTL
+
+## Examples
+
+See the [`examples/`](./examples/) directory for working scripts:
+
+- **[`basic-push.sh`](./examples/basic-push.sh)** — Push a macro-tracker page with curl
+- **[`compose-page.sh`](./examples/compose-page.sh)** — Compose a page from individual components
+- **[`manage-pages.sh`](./examples/manage-pages.sh)** — Full page lifecycle: list, update, delete
+- **[`node-client.js`](./examples/node-client.js)** — Node.js client with WebSocket event listener
+
+## Configuration
+
+| Environment Variable | Default | Description |
+|---------------------|---------|-------------|
+| `SPARKUI_PORT` | `3457` | Server port |
+| `PUSH_TOKEN` | *(required)* | Auth token for push/compose/manage APIs |
+| `SPARKUI_BASE_URL` | `http://localhost:3457` | Public URL for generated links |
+| `OPENCLAW_HOOKS_URL` | *(optional)* | OpenClaw webhook URL for event forwarding |
+| `OPENCLAW_HOOKS_TOKEN` | *(optional)* | Auth token for OpenClaw webhook |
+
+## OpenClaw Skill
+
+SparkUI includes an [OpenClaw](https://github.com/openclaw/openclaw) skill for direct agent integration. See [SKILL.md](./SKILL.md) for details.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## Documentation
+
+Full documentation is available in the [`docs/`](./docs/) directory:
+
+- **[Getting Started](./docs/getting-started.md)** — Install, configure, and push your first page
+- **[API Reference](./docs/api-reference.md)** — REST API and WebSocket protocol
+- **[Templates](./docs/templates.md)** — 5 built-in templates with schemas and examples
+- **[Components](./docs/components.md)** — 8 composable components for custom pages
+- **[MCP Setup](./docs/mcp-setup.md)** — Claude Desktop, Cursor, and Windsurf integration
+- **[OpenClaw Setup](./docs/openclaw-setup.md)** — Agent skill integration
+- **[ChatGPT Setup](./docs/chatgpt-setup.md)** — Custom GPT Actions integration
+
+## Related
+
+- **[MCP Server](./mcp-server/README.md)** — Use SparkUI from Claude Desktop, Cursor, or Windsurf
+- **[Examples](./examples/README.md)** — Working scripts and code samples
+- **[Contributing](./CONTRIBUTING.md)** — Setup, testing, and PR guidelines
+
+## License
+
+[MIT](./LICENSE) © [Limeade Labs](https://limeadelabs.com)

package/SKILL.md

@@ -0,0 +1,242 @@
+# SparkUI — Ephemeral Web UI Generator
+
+## When to Use
+Use SparkUI when the user needs something **visual** that's better as a web page than chat text:
+- **Dashboards** — nutrition trackers, fitness stats, project metrics
+- **Data displays** — tables, charts, comparisons
+- **Trackers** — daily logs, progress views
+- **Rich content** — anything with colors, progress bars, layouts
+
+**Don't use** for simple text answers, yes/no questions, or quick lists that work fine in chat.
+
+## Server Location
+- **Directory:** `/home/clawd/projects/sparkui/`
+- **Port:** 3457 (configured in .env; override with `SPARKUI_PORT` env)
+- **Config:** Push token is in `/home/clawd/projects/sparkui/.env`
+
+## Step 1: Ensure Server is Running
+
+```bash
+# Check if running
+curl -s http://localhost:3457/ | head -c 200
+
+# If not running, start it:
+cd /home/clawd/projects/sparkui && node server.js &
+```
+
+Use `exec` with `background: true` to start the server if it's down.
+
+## Step 2: Get the Push Token
+
+```bash
+source /home/clawd/projects/sparkui/.env  # loads PUSH_TOKEN and SPARKUI_PORT
+```
+
+## Step 3: Push Content
+
+### Using a Template (preferred for known types)
+
+```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-10",
+      "calories": {"current": 1250, "target": 1900},
+      "protein": {"current": 62, "target": 86},
+      "fat": {"current": 45, "target": 95},
+      "carbs": {"current": 120, "target": 175},
+      "meals": [
+        {"name": "Oatmeal with berries", "calories": 350, "time": "6:30 AM"},
+        {"name": "Grilled chicken salad", "calories": 480, "time": "12:00 PM"},
+        {"name": "Greek yogurt", "calories": 150, "time": "3:00 PM"}
+      ]
+    },
+    "ttl": 7200
+  }'
+```
+
+### Using Raw HTML
+
+```bash
+curl -s -X POST http://localhost:3457/api/push \
+  -H "Authorization: Bearer $PUSH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"html": "<html>...</html>", "ttl": 3600}'
+```
+
+For raw HTML, use the dark theme (#111 bg, #e0e0e0 text, -apple-system font) to match SparkUI's design language.
+
+### Updating a Page
+
+```bash
+curl -s -X PATCH http://localhost:3457/api/pages/PAGE_ID \
+  -H "Authorization: Bearer $PUSH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"template": "macro-tracker", "data": {...}}'
+```
+
+## Step 4: Share the Link
+
+The push API returns `{ id, url, fullUrl }`. Share the `fullUrl` with the user.
+
+**Important:** The server runs on localhost. For the user to access it, they need network access to the host. If behind a tunnel (e.g., Cloudflare Tunnel, ngrok), set `SPARKUI_BASE_URL` env var to the public URL.
+
+## Available Templates
+
+| Template | Description | Data Shape |
+|----------|-------------|------------|
+| `macro-tracker` | Nutrition macro dashboard | `{date, calories, protein, fat, carbs, meals}` — each macro has `{current, target}`, meals is `[{name, calories, time}]` |
+| `feedback-form` | Rating + text feedback form | `{title, subtitle?, questions?}` — questions is optional `string[]` for extra text fields |
+
+## OpenClaw Round-Trip (Event Callbacks)
+
+When you want SparkUI to report user interactions back to the agent via OpenClaw webhooks, add `openclaw` config to the push request. This closes the loop: **agent pushes page → user interacts → agent gets notified**.
+
+### Push with OpenClaw Config
+
+```bash
+curl -s -X POST http://localhost:3457/api/push \
+  -H "Authorization: Bearer $PUSH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "template": "feedback-form",
+    "data": {"title": "Quick Feedback", "subtitle": "How was the experience?"},
+    "openclaw": {
+      "enabled": true,
+      "channel": "slack",
+      "to": "YOUR_CHANNEL_ID",
+      "eventTypes": ["completion"]
+    }
+  }'
+```
+
+### OpenClaw Config Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `enabled` | boolean | yes | Enable OpenClaw forwarding |
+| `channel` | string | no | Delivery channel (default: "slack") |
+| `to` | string | no | Target channel/user ID (e.g., "YOUR_CHANNEL_ID" for #sparkui) |
+| `eventTypes` | string[] | no | Which events to forward: `["completion"]`, `["event"]`, or `["event", "completion"]`. Default: `["completion"]` |
+| `sessionKey` | string | no | Optional session key override for routing |
+
+### How It Works
+
+1. Agent pushes a page with `openclaw` config
+2. User opens the page and interacts (clicks, submits form)
+3. Browser sends events via WebSocket to SparkUI server
+4. SparkUI server checks `openclaw` config and forwards matching events to OpenClaw's `/hooks/agent` endpoint
+5. OpenClaw delivers the message to the specified channel
+6. Agent receives the message and can respond
+
+### When to Use OpenClaw Round-Trip
+
+- **Feedback forms** — get notified when user submits
+- **Approval workflows** — user clicks approve/reject
+- **Interactive quizzes** — collect answers
+- **Any form** — completion events carry all form data
+
+### Environment Variables
+
+Set these in `.env` (already configured):
+```
+OPENCLAW_HOOKS_URL=http://127.0.0.1:18789/hooks/agent
+OPENCLAW_HOOKS_TOKEN=your_openclaw_hooks_token
+```
+
+## Composable Components (Preferred)
+
+Instead of raw HTML or monolithic templates, use the **compose API** to assemble pages from reusable components. This is the fastest path — under 3 seconds from request to rendered UI.
+
+### POST /api/compose
+
+```bash
+curl -s -X POST http://localhost:3457/api/compose \
+  -H "Authorization: Bearer $PUSH_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Page Title",
+    "sections": [
+      { "type": "header", "config": { "title": "Hello", "subtitle": "World", "icon": "⚡", "badge": "New" } },
+      { "type": "checklist", "config": { "items": [{"text": "Item 1"}, {"text": "Item 2"}], "showProgress": true, "allowAdd": true } },
+      { "type": "button", "config": { "label": "Done", "action": "complete", "style": "primary" } }
+    ],
+    "openclaw": { "enabled": true, "channel": "slack", "to": "YOUR_CHANNEL_ID" }
+  }'
+```
+
+Returns `{ id, url, fullUrl }` — ready to share.
+
+### Available Components
+
+| Component | Config | Description |
+|-----------|--------|-------------|
+| `header` | `{ title, subtitle?, icon?, badge? }` | Page header with optional icon/badge |
+| `button` | `{ label, action, style?, icon?, disabled? }` | Clickable button. Styles: `primary` (green), `secondary` (outline), `danger` (red). Sends `event` with `{action}` |
+| `timer` | `{ mode, duration?, intervals?, autoStart? }` | Modes: `countdown` (duration in secs), `stopwatch`, `interval` (array of `{label, seconds}`). Sends `timer` event on complete |
+| `checklist` | `{ items: [{text, checked?}], allowAdd?, showProgress? }` | Interactive checklist with progress bar. Sends `completion` when all checked |
+| `progress` | `{ value, max, label?, color?, showPercent?, segments? }` | Single bar or multi-segment. Segments: `[{label, value, max, color}]` |
+| `stats` | `{ items: [{label, value, unit?, icon?, trend?}] }` | 2-column grid of stat cards. Trend: `up`/`down`/`flat` |
+| `form` | `{ fields: [{type, name, label, placeholder?, options?, required?}], submitLabel? }` | Form with text/number/select/textarea/rating fields. Sends `completion` with `{formData}` |
+| `tabs` | `{ tabs: [{label, content}], activeIndex? }` | Tab switcher. Content can be HTML strings (including other component output) |
+
+### Component Examples
+
+**Workout Timer:**
+```json
+{ "type": "timer", "config": { "mode": "interval", "intervals": [
+  {"label": "Work", "seconds": 30}, {"label": "Rest", "seconds": 10},
+  {"label": "Work", "seconds": 30}, {"label": "Rest", "seconds": 10}
+] } }
+```
+
+**Stats Dashboard:**
+```json
+{ "type": "stats", "config": { "items": [
+  {"label": "Weight", "value": "222", "unit": "lbs", "icon": "⚖️", "trend": "down"},
+  {"label": "Streak", "value": "5", "unit": "days", "icon": "🔥", "trend": "up"}
+] } }
+```
+
+**Multi-Segment Progress:**
+```json
+{ "type": "progress", "config": { "segments": [
+  {"label": "Protein", "value": 62, "max": 86, "color": "#ff6b6b"},
+  {"label": "Fat", "value": 45, "max": 95, "color": "#ffd93d"},
+  {"label": "Carbs", "value": 120, "max": 175, "color": "#6bcb77"}
+] } }
+```
+
+**Feedback Form:**
+```json
+{ "type": "form", "config": {
+  "fields": [
+    {"type": "rating", "name": "rating", "label": "How was it?"},
+    {"type": "textarea", "name": "feedback", "label": "Comments", "placeholder": "Tell us more..."}
+  ],
+  "submitLabel": "Send"
+} }
+```
+
+### When to Use Compose vs Templates
+
+- **Compose** — for any new page, custom layouts, mixing components. This is the default choice.
+- **Templates** — only for `macro-tracker` (has specialized chart logic) or when exact existing template behavior is needed.
+
+## Example Flow: Daily Macro Tracking
+
+1. User says "log my lunch — chicken sandwich, 450 cal, 35g protein, 15g fat, 40g carbs"
+2. Agent updates the nutrition spreadsheet
+3. Agent reads today's totals from the sheet
+4. Agent pushes a macro-tracker page with the current totals
+5. Agent shares the link: "Here's your updated dashboard: http://..."
+6. If the page already exists from earlier, use PATCH to update it instead of creating a new one
+
+## Notes
+- Pages expire after their TTL (default 1 hour). This is by design — they're ephemeral.
+- The macro-tracker template auto-refreshes every 30 seconds.
+- WebSocket support is built in — pages will auto-reload when updated via PATCH.
+- For longer-lived pages, set a higher TTL (e.g., 86400 for 24h).

package/bin/deploy

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -e
+
+echo "🚀 Deploying SparkUI..."
+
+# Restart the service (adjust to your process manager)
+# systemctl --user restart sparkui
+# pm2 restart sparkui
+
+echo "✅ SparkUI restarted"
+
+# Quick health check
+sleep 1
+PORT="${SPARKUI_PORT:-3456}"
+STATUS=$(curl -s "http://localhost:${PORT}/" | jq -r '.status // "unknown"' 2>/dev/null)
+echo ""
+echo "Health check: $STATUS"
+
+# Check public URL (if configured)
+if [ -n "$SPARKUI_BASE_URL" ]; then
+  PUB_STATUS=$(curl -s "$SPARKUI_BASE_URL/" | jq -r '.status // "unknown"' 2>/dev/null)
+  echo "Public URL:   $PUB_STATUS"
+fi