@limeade-labs/sparkui 1.0.0

package/lib/templates.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const path = require('path');
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+// Registry of known templates
+const registry = {
+  'macro-tracker': require(path.join(TEMPLATES_DIR, 'macro-tracker')),
+  'ws-test': require(path.join(TEMPLATES_DIR, 'ws-test')),
+  'feedback-form': require(path.join(TEMPLATES_DIR, 'feedback-form')),
+  'checkout': require(path.join(TEMPLATES_DIR, 'checkout')),
+  'workout-timer': require(path.join(TEMPLATES_DIR, 'workout-timer')),
+};
+
+/**
+ * Render a named template with data.
+ * @param {string} name - Template name (e.g. "macro-tracker")
+ * @param {object} data - Template data
+ * @returns {string} Rendered HTML
+ * @throws {Error} if template not found
+ */
+function render(name, data) {
+  const templateFn = registry[name];
+  if (!templateFn) {
+    const available = Object.keys(registry).join(', ');
+    throw new Error(`Unknown template "${name}". Available: ${available}`);
+  }
+  return templateFn(data);
+}
+
+/**
+ * Check if a template exists.
+ * @param {string} name
+ * @returns {boolean}
+ */
+function has(name) {
+  return name in registry;
+}
+
+/**
+ * List available template names.
+ * @returns {string[]}
+ */
+function list() {
+  return Object.keys(registry);
+}
+
+module.exports = { render, has, list };

package/lib/ws-client.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * Client-side WebSocket code for SparkUI pages.
+ * Exported as a string so it can be inlined into HTML templates.
+ * No external dependencies.
+ */
+
+const WS_CLIENT_JS = `
+(function() {
+  'use strict';
+
+  var pageId = window.__SPARKUI_PAGE_ID__;
+  if (!pageId) return;
+
+  var proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+  var wsUrl = proto + '//' + location.host + '/ws?page=' + encodeURIComponent(pageId);
+
+  var ws = null;
+  var reconnectDelay = 1000;
+  var maxReconnectDelay = 30000;
+  var heartbeatTimer = null;
+  var connected = false;
+  var messageHandlers = [];
+  var pendingQueue = [];
+  var completionData = {};
+
+  // ── Connection Management ──
+
+  function connect() {
+    if (ws && (ws.readyState === WebSocket.CONNECTING || ws.readyState === WebSocket.OPEN)) return;
+
+    try { ws = new WebSocket(wsUrl); } catch(e) { scheduleReconnect(); return; }
+
+    ws.onopen = function() {
+      connected = true;
+      reconnectDelay = 1000;
+      startHeartbeat();
+      dispatchStatus('connected');
+
+      // Flush pending messages
+      while (pendingQueue.length > 0) {
+        var msg = pendingQueue.shift();
+        try { ws.send(msg); } catch(e) {}
+      }
+    };
+
+    ws.onmessage = function(e) {
+      try {
+        var msg = JSON.parse(e.data);
+      } catch(err) { return; }
+
+      // Handle built-in message types
+      if (msg.type === 'update') {
+        location.reload();
+        return;
+      }
+
+      if (msg.type === 'destroy') {
+        stopHeartbeat();
+        document.body.innerHTML = '<div style="background:#111;color:#888;font-family:-apple-system,sans-serif;display:flex;align-items:center;justify-content:center;height:100vh;margin:0"><div style="text-align:center"><h1 style="font-size:3rem;margin-bottom:8px">⚡</h1><p>This page has expired or been removed.</p><p style="color:#555;font-size:0.85rem">SparkUI pages are ephemeral by design.</p></div></div>';
+        return;
+      }
+
+      if (msg.type === 'pong') {
+        // Server heartbeat response, connection is alive
+        return;
+      }
+
+      // Dispatch to registered handlers
+      for (var i = 0; i < messageHandlers.length; i++) {
+        try { messageHandlers[i](msg); } catch(err) { console.error('[sparkui] handler error:', err); }
+      }
+    };
+
+    ws.onclose = function() {
+      connected = false;
+      stopHeartbeat();
+      dispatchStatus('disconnected');
+      scheduleReconnect();
+    };
+
+    ws.onerror = function() {
+      // onclose will fire after this
+    };
+  }
+
+  function scheduleReconnect() {
+    setTimeout(function() {
+      connect();
+    }, reconnectDelay);
+    reconnectDelay = Math.min(reconnectDelay * 2, maxReconnectDelay);
+  }
+
+  // ── Heartbeat ──
+
+  function startHeartbeat() {
+    stopHeartbeat();
+    heartbeatTimer = setInterval(function() {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        try { ws.send(JSON.stringify({ type: 'heartbeat' })); } catch(e) {}
+      }
+    }, 25000);
+  }
+
+  function stopHeartbeat() {
+    if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+  }
+
+  // ── Send Messages ──
+
+  function send(type, data) {
+    var msg = JSON.stringify({ type: type, pageId: pageId, data: data || {}, timestamp: Date.now() });
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      try { ws.send(msg); } catch(e) { pendingQueue.push(msg); }
+    } else {
+      pendingQueue.push(msg);
+    }
+  }
+
+  // ── Event Handlers ──
+
+  function onMessage(handler) {
+    if (typeof handler === 'function') messageHandlers.push(handler);
+  }
+
+  function offMessage(handler) {
+    messageHandlers = messageHandlers.filter(function(h) { return h !== handler; });
+  }
+
+  // ── Status Dispatch ──
+
+  function dispatchStatus(status) {
+    var event;
+    try {
+      event = new CustomEvent('sparkui:status', { detail: { status: status, pageId: pageId } });
+    } catch(e) {
+      event = document.createEvent('CustomEvent');
+      event.initCustomEvent('sparkui:status', true, true, { status: status, pageId: pageId });
+    }
+    document.dispatchEvent(event);
+  }
+
+  // ── Completion on Unload ──
+
+  function setCompletionData(data) {
+    completionData = data || {};
+  }
+
+  function sendCompletion(data) {
+    var payload = data || completionData;
+    send('completion', payload);
+  }
+
+  // Send completion on page unload
+  window.addEventListener('beforeunload', function() {
+    if (ws && ws.readyState === WebSocket.OPEN && Object.keys(completionData).length > 0) {
+      // Use sendBeacon-style: just try to send, no guarantee
+      try { ws.send(JSON.stringify({ type: 'completion', pageId: pageId, data: completionData, timestamp: Date.now() })); } catch(e) {}
+    }
+  });
+
+  // ── Public API ──
+
+  window.sparkui = {
+    send: send,
+    onMessage: onMessage,
+    offMessage: offMessage,
+    setCompletionData: setCompletionData,
+    sendCompletion: sendCompletion,
+    get connected() { return connected; },
+    get pageId() { return pageId; }
+  };
+
+  // Auto-connect
+  connect();
+})();
+`;
+
+/**
+ * Get the client JS with pageId injected.
+ * @param {string} pageId
+ * @returns {string} Script tag content
+ */
+function getClientScript(pageId) {
+  return WS_CLIENT_JS.replace('window.__SPARKUI_PAGE_ID__', JSON.stringify(pageId));
+}
+
+/**
+ * Get the raw client JS string (for manual injection).
+ * @returns {string}
+ */
+function getRawClientJS() {
+  return WS_CLIENT_JS;
+}
+
+module.exports = { getClientScript, getRawClientJS };

package/mcp-server/README.md

@@ -0,0 +1,189 @@
+# SparkUI MCP Server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes SparkUI as tools for AI clients like Claude Desktop, Cursor, Windsurf, and Cline.
+
+Any MCP-compatible client can create ephemeral web pages on the fly — checkout flows, workout timers, dashboards, forms — through natural language.
+
+## Installation
+
+```bash
+cd mcp-server
+npm install
+```
+
+## Configuration
+
+The server uses two environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `SPARKUI_URL` | Base URL of the SparkUI server | `http://localhost:3457` |
+| `SPARKUI_TOKEN` | Push API authentication token | *(required)* |
+
+## Claude Desktop Setup
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+
+```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"
+      }
+    }
+  }
+}
+```
+
+## Cursor / Windsurf Setup
+
+Add to `.cursor/mcp.json` or `.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"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `sparkui_list_templates`
+
+List available page templates.
+
+**Parameters:** None
+
+**Returns:**
+```json
+{
+  "templates": ["macro-tracker", "checkout", "workout-timer", "feedback-form", "ws-test"]
+}
+```
+
+### `sparkui_list_components`
+
+List available components for composing pages.
+
+**Parameters:** None
+
+**Returns:**
+```json
+{
+  "components": ["header", "button", "timer", "checklist", "progress", ...]
+}
+```
+
+### `sparkui_push`
+
+Create a page from a template.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `template` | string | ✅ | Template name (e.g. `"checkout"`) |
+| `data` | object | ✅ | Template data |
+| `ttl` | number | | Time-to-live in seconds (default: 3600) |
+| `og` | object | | Open Graph overrides `{title, description, image}` |
+
+**Example:**
+```json
+{
+  "template": "checkout",
+  "data": {
+    "title": "Your Order",
+    "items": [{"name": "Widget", "price": 9.99, "qty": 2}],
+    "total": 19.98
+  },
+  "ttl": 7200
+}
+```
+
+**Returns:**
+```json
+{
+  "id": "abc-123-...",
+  "url": "/s/abc-123-...",
+  "fullUrl": "http://localhost:3457/s/abc-123-..."
+}
+```
+
+### `sparkui_compose`
+
+Compose a page from individual components.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `title` | string | ✅ | Page title |
+| `sections` | array | ✅ | Array of `{type, config}` sections |
+| `ttl` | number | | Time-to-live in seconds |
+
+**Example:**
+```json
+{
+  "title": "Quick Poll",
+  "sections": [
+    {"type": "header", "config": {"text": "What should we build?"}},
+    {"type": "checklist", "config": {"items": ["Feature A", "Feature B", "Feature C"]}}
+  ]
+}
+```
+
+**Returns:**
+```json
+{
+  "id": "def-456-...",
+  "url": "/s/def-456-...",
+  "fullUrl": "http://localhost:3457/s/def-456-..."
+}
+```
+
+### `sparkui_page_status`
+
+Check if a page exists and whether it's still active.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|---|---|---|---|
+| `id` | string | ✅ | Page UUID |
+
+**Returns:**
+```json
+{
+  "exists": true,
+  "status": "active",
+  "url": "/s/abc-123-...",
+  "fullUrl": "http://localhost:3457/s/abc-123-..."
+}
+```
+
+## How It Works
+
+The MCP server communicates with the SparkUI HTTP API over HTTP. It does **not** import SparkUI internals — it's a standalone client that calls `POST /api/push`, `POST /api/compose`, and `GET /` on the SparkUI server.
+
+```
+Claude Desktop / Cursor / Windsurf
+        ↓ (MCP stdio)
+   SparkUI MCP Server
+        ↓ (HTTP)
+   SparkUI Server (localhost:3457)
+        ↓
+   Ephemeral web pages
+```
+
+## License
+
+MIT

package/mcp-server/index.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+'use strict';
+
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { z } = require('zod/v4');
+
+// ── Config ───────────────────────────────────────────────────────────────────
+
+const SPARKUI_URL = (process.env.SPARKUI_URL || 'http://localhost:3457').replace(/\/+$/, '');
+const SPARKUI_TOKEN = process.env.SPARKUI_TOKEN || '';
+
+// ── HTTP helper ──────────────────────────────────────────────────────────────
+
+async function sparkuiRequest(method, path, body) {
+  const url = `${SPARKUI_URL}${path}`;
+  const headers = { 'Content-Type': 'application/json' };
+  if (SPARKUI_TOKEN) {
+    headers['Authorization'] = `Bearer ${SPARKUI_TOKEN}`;
+  }
+
+  const options = { method, headers };
+  if (body) options.body = JSON.stringify(body);
+
+  const res = await fetch(url, options);
+  const data = await res.json();
+
+  if (!res.ok) {
+    throw new Error(data.error || `SparkUI API error: ${res.status}`);
+  }
+  return data;
+}
+
+// ── MCP Server ───────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+  name: 'sparkui',
+  version: '0.1.0',
+});
+
+// Tool: sparkui_list_templates
+server.tool(
+  'sparkui_list_templates',
+  'List available SparkUI page templates. Returns template names that can be used with sparkui_push.',
+  {},
+  async () => {
+    const data = await sparkuiRequest('GET', '/');
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ templates: data.templates }, null, 2) }],
+    };
+  }
+);
+
+// Tool: sparkui_list_components
+server.tool(
+  'sparkui_list_components',
+  'List available SparkUI components for composing pages with sparkui_compose.',
+  {},
+  async () => {
+    const components = [
+      'header', 'button', 'timer', 'checklist', 'progress',
+      'text', 'image', 'divider', 'card', 'input',
+      'select', 'table', 'chart', 'code', 'form'
+    ];
+    return {
+      content: [{ type: 'text', text: JSON.stringify({ components }, null, 2) }],
+    };
+  }
+);
+
+// Tool: sparkui_push
+server.tool(
+  'sparkui_push',
+  'Push a page from a SparkUI template. Returns the page ID and URL.',
+  {
+    template: z.string().describe('Template name (e.g. "checkout", "macro-tracker", "workout-timer")'),
+    data: z.record(z.string(), z.any()).describe('Template data object'),
+    ttl: z.optional(z.number().describe('Time-to-live in seconds (default 3600)')),
+    og: z.optional(z.object({
+      title: z.optional(z.string()),
+      description: z.optional(z.string()),
+      image: z.optional(z.string()),
+    }).describe('Open Graph metadata overrides')),
+  },
+  async ({ template, data, ttl, og }) => {
+    const body = { template, data };
+    if (ttl !== undefined) body.ttl = ttl;
+    if (og) body.og = og;
+
+    const result = await sparkuiRequest('POST', '/api/push', body);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+// Tool: sparkui_compose
+server.tool(
+  'sparkui_compose',
+  'Compose a page from SparkUI components. Returns the page ID and URL.',
+  {
+    title: z.string().describe('Page title'),
+    sections: z.array(z.object({
+      type: z.string().describe('Component type (e.g. "header", "button", "timer", "checklist")'),
+      config: z.optional(z.record(z.string(), z.any()).describe('Component configuration')),
+    })).describe('Array of sections to compose'),
+    ttl: z.optional(z.number().describe('Time-to-live in seconds')),
+  },
+  async ({ title, sections, ttl }) => {
+    const body = { title, sections };
+    if (ttl !== undefined) body.ttl = ttl;
+
+    const result = await sparkuiRequest('POST', '/api/compose', body);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  }
+);
+
+// Tool: sparkui_page_status
+server.tool(
+  'sparkui_page_status',
+  'Check if a SparkUI page exists and get its status.',
+  {
+    id: z.string().describe('Page UUID'),
+  },
+  async ({ id }) => {
+    try {
+      const url = `${SPARKUI_URL}/s/${id}`;
+      const res = await fetch(url);
+
+      if (res.status === 410) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ exists: false, status: 'expired' }, null, 2) }],
+        };
+      }
+
+      if (res.status === 404) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ exists: false, status: 'not_found' }, null, 2) }],
+        };
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            exists: true,
+            status: 'active',
+            url: `/s/${id}`,
+            fullUrl: `${SPARKUI_URL}/s/${id}`,
+          }, null, 2),
+        }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({ exists: false, error: err.message }, null, 2) }],
+      };
+    }
+  }
+);
+
+// ── Start ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('SparkUI MCP server running on stdio');
+}
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/mcp-server/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@sparkui/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server exposing SparkUI as tools for Claude Desktop, Cursor, Windsurf, and other MCP clients",
+  "main": "index.js",
+  "bin": {
+    "sparkui-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@limeade-labs/sparkui",
+  "version": "1.0.0",
+  "description": "Ephemeral, purpose-built web UIs generated on demand from chat conversations",
+  "main": "server.js",
+  "bin": {
+    "sparkui": "./bin/sparkui.js"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node server.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "server.js",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    ".env.example",
+    "docs/",
+    "SKILL.md",
+    "mcp-server/index.js",
+    "mcp-server/package.json",
+    "mcp-server/README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "sparkui",
+    "ephemeral-ui",
+    "ai-agent",
+    "web-ui",
+    "mcp",
+    "websocket",
+    "templates"
+  ],
+  "homepage": "https://sparkui.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/limeade-labs/sparkui.git"
+  },
+  "author": "Limeade Labs",
+  "license": "MIT",
+  "dependencies": {
+    "express": "^4.21.0",
+    "uuid": "^11.1.0",
+    "ws": "^8.18.0"
+  }
+}