npm - @khanglvm/relay - Versions diffs - 0.10.2 → 0.11.0 - Mend

@khanglvm/relay 0.10.2 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/src/mcp-ui/index.html ADDED Viewed

@@ -0,0 +1,36 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light dark">
+<title>__TITLE__</title>
+<style>/*__CSS__*/
+/*__BLOCKS_CSS__*/
+/* MCP-app inline tweaks: the host owns the outer chrome, so the board paints
+   edge-to-edge with no min-height / page background of its own. */
+:root{ color-scheme: light dark; }
+html,body{ background:transparent; }
+body{ margin:0; }
+.wrap{ max-width:none; margin:0; padding:14px 16px 18px; }
+.mcp-status{ font:13px/1.5 var(--sans, -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif); color:var(--muted,#8a8580); padding:18px 16px; }
+/* post-submit: a slim one-line confirmation so the iframe collapses small */
+.mcp-done{ display:flex; align-items:center; gap:8px; padding:11px 16px; font:14px/1.4 var(--sans, -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif); color:var(--fg,#1c1b19); }
+.mcp-done .mark{ font-size:15px; font-weight:700; color:var(--ok,#4d8a66); }
+.mcp-done .lead{ font-weight:600; }
+.mcp-done .sub{ color:var(--muted,#8a8580); }
+/* in fullscreen the host fills the window — keep text to a readable column */
+.mcp-fullscreen .wrap{ max-width:760px; margin:0 auto; }
+/* progressive preview: shown while the agent is still streaming the spec */
+.mcp-composing{ font-size:13px; color:var(--muted,#8a8580); display:inline-flex; align-items:center; gap:7px; }
+.mcp-composing::before{ content:""; width:7px; height:7px; border-radius:50%; background:var(--accent,#c2674b); animation:mcp-pulse 1s var(--ease,ease) infinite; }
+@keyframes mcp-pulse{ 0%,100%{ opacity:.25; } 50%{ opacity:1; } }
+</style>
+</head>
+<body>
+<script id="boot" type="application/json">__BOOT_JSON__</script>
+<div id="app" class="wrap"><div class="mcp-status" id="mcp-status">Loading the relay board…</div></div>
+<script>/*__BLOCKS_JS__*/</script>
+<script>/*__BOARD_JS__*/</script>
+</body>
+</html>

package/src/mcp.js ADDED Viewed

@@ -0,0 +1,451 @@
+// mcp.js — relay as an MCP App (SEP-1865, extension "io.modelcontextprotocol/ui").
+//
+// `rly mcp` starts a zero-dependency MCP server over stdio. Register it with a
+// host that supports MCP Apps (Claude desktop/mobile, Codex, …) and relay's
+// boards render INLINE in the conversation instead of opening a browser tab:
+//
+//   • the server declares a UI resource  ui://relay/board  (text/html;profile=mcp-app)
+//   • the tools `relay_ask` / `relay_show` link to it via _meta.ui.resourceUri
+//   • calling a tool returns the (normalized) board spec as structuredContent;
+//     the host renders the resource in a sandboxed iframe and forwards the spec
+//   • the iframe collects the user's answers and sends them back to the model
+//     via `ui/update-model-context`
+//
+// Framing is the MCP stdio transport: newline-delimited JSON-RPC, one message
+// per line, never embedded newlines. stdout carries ONLY protocol messages;
+// everything else goes to stderr.
+import fs from 'node:fs';
+import path from 'node:path';
+import http from 'node:http';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { normalizeSpec, SPEC_SCHEMA } from './spec.js';
+import { CliError } from './util.js';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const UI_DIR = path.join(__dirname, 'ui');
+const MCP_UI_DIR = path.join(__dirname, 'mcp-ui');
+const PKG_ROOT = path.join(__dirname, '..');
+const VENDOR_DIR = path.join(PKG_ROOT, 'vendor');
+const PKG = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+const UI_EXT = 'io.modelcontextprotocol/ui';
+const UI_MIME = 'text/html;profile=mcp-app';
+const BOARD_URI = 'ui://relay/board';
+const VENDOR_PREFIX = 'ui://relay/vendor/';
+// Echoed back to the client when it doesn't pin a version we recognize.
+const DEFAULT_PROTOCOL = '2025-06-18';
+const DEFAULT_HTTP_PORT = 4319;
+const escapeHtml = (s) =>
+  String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+// ---------- UI asset assembly (cached for the process lifetime) ----------
+const _cache = new Map();
+function readAsset(dir, name) {
+  const key = dir + '\0' + name;
+  if (_cache.has(key)) return _cache.get(key);
+  let content = '';
+  try { content = fs.readFileSync(path.join(dir, name), 'utf8'); } catch { content = ''; }
+  _cache.set(key, content);
+  return content;
+}
+// The single self-contained board page served as the ui:// resource: the shared
+// stylesheet + block renderer + the MCP-app client, all inlined (no /vendor or
+// /api routes exist in the sandbox; vendors load over the bridge on demand).
+function buildBoardPage() {
+  if (_cache.has('__page__')) return _cache.get('__page__');
+  const html = readAsset(MCP_UI_DIR, 'index.html');
+  const boot = { version: PKG.version, boardId: 'mcp-' + Date.now().toString(36) };
+  const page = html
+    .split('__TITLE__').join('Relay')
+    .split('/*__CSS__*/').join(readAsset(UI_DIR, 'style.css'))
+    .split('/*__BLOCKS_CSS__*/').join(readAsset(UI_DIR, 'blocks.css'))
+    .split('/*__BLOCKS_JS__*/').join(readAsset(UI_DIR, 'blocks.js'))
+    .split('/*__BOARD_JS__*/').join(readAsset(MCP_UI_DIR, 'board.js'))
+    .split('__BOOT_JSON__').join(JSON.stringify(boot).replace(/</g, '\\u003c'));
+  _cache.set('__page__', page);
+  return page;
+}
+function vendorText(name) {
+  // No traversal: only a bare filename inside VENDOR_DIR.
+  if (!/^[\w.-]+$/.test(name)) return null;
+  const target = path.join(VENDOR_DIR, name);
+  if (target !== VENDOR_DIR && !target.startsWith(VENDOR_DIR + path.sep)) return null;
+  try { return fs.readFileSync(target, 'utf8'); } catch { return null; }
+}
+// ---------- tool + resource descriptors ----------
+// The board spec, as the tool input schema: SPEC_SCHEMA minus the result-only
+// fields (annotations / blockEdits are returned, never supplied).
+function inputSchema() {
+  const props = { ...SPEC_SCHEMA.properties };
+  delete props.annotations;
+  delete props.blockEdits;
+  return { type: 'object', properties: props, anyOf: SPEC_SCHEMA.anyOf };
+}
+// _meta linking a tool to the UI resource. We emit the field under several keys
+// for cross-host compatibility: the spec's `_meta.ui`, the extension-id key, and
+// OpenAI's `openai/outputTemplate` (ChatGPT / Codex Apps SDK).
+function uiToolMeta() {
+  const ui = { resourceUri: BOARD_URI, visibility: ['model', 'app'] };
+  return { ui, [UI_EXT]: ui, 'openai/outputTemplate': BOARD_URI };
+}
+function tools() {
+  const schema = inputSchema();
+  return [
+    {
+      name: 'relay_ask',
+      description:
+        'Ask the user structured questions on an interactive board rendered inline in this app — real form controls (single/multi choice, yes/no, scale, text) plus rich blocks (markdown, code, diff, table, chart, mermaid, graphviz, image, html). Use this instead of asking questions in plain text whenever you need decisions, requirements, or feedback. The user fills it in and submits; their answers come back to you. Pass a board spec (see inputSchema).',
+      inputSchema: schema,
+      _meta: uiToolMeta(),
+    },
+    {
+      name: 'relay_show',
+      description:
+        'Present work to the user on an inline board WITHOUT necessarily asking questions — a plan, an architecture diagram, data, a diff, a prototype — using rich blocks (markdown, mermaid, graphviz, chart, table, code, diff, image, html). The board shows a Submit/Acknowledge button. Same spec as relay_ask; typically blocks-only.',
+      inputSchema: schema,
+      _meta: uiToolMeta(),
+    },
+  ];
+}
+function resources() {
+  return [
+    {
+      uri: BOARD_URI,
+      name: 'Relay board',
+      description: 'The interactive relay board UI (rendered inline by relay_ask / relay_show).',
+      mimeType: UI_MIME,
+      _meta: { ui: resourceMeta() },
+    },
+  ];
+}
+// Per-resource UI hints (CSP / framing). Hosts that ignore these still work; the
+// frame allowances cover YouTube/Vimeo `video` blocks and blob: html previews.
+function resourceMeta() {
+  return {
+    prefersBorder: false,
+    csp: {
+      connectDomains: [],
+      resourceDomains: ['https://*', 'data:', 'blob:'],
+      frameDomains: ['https://www.youtube-nocookie.com', 'https://player.vimeo.com', 'blob:', 'data:'],
+    },
+  };
+}
+// ---------- request routing ----------
+function buildResult(method, params, clientProtocol) {
+  switch (method) {
+    case 'initialize':
+      return {
+        protocolVersion: typeof params.protocolVersion === 'string' ? params.protocolVersion : DEFAULT_PROTOCOL,
+        capabilities: {
+          tools: { listChanged: false },
+          resources: { listChanged: false },
+          experimental: {},
+          extensions: { [UI_EXT]: { mimeTypes: [UI_MIME] } },
+        },
+        serverInfo: { name: 'relay', version: PKG.version },
+        instructions:
+          'relay renders interactive boards inline. Call relay_ask to collect decisions/feedback with real form controls, or relay_show to present plans/diagrams/data — instead of asking in plain text. Read the user\'s answers from the structuredContent that returns after they submit.',
+      };
+    case 'ping':
+      return {};
+    case 'tools/list':
+      return { tools: tools() };
+    case 'resources/list':
+      return { resources: resources() };
+    case 'resources/templates/list':
+      return { resourceTemplates: [] };
+    case 'prompts/list':
+      return { prompts: [] };
+    case 'resources/read':
+      return readResource(params);
+    case 'tools/call':
+      return callTool(params);
+    default: {
+      const err = new Error('method not found: ' + method);
+      err.code = -32601;
+      throw err;
+    }
+  }
+}
+function readResource(params) {
+  const uri = params && params.uri;
+  if (uri === BOARD_URI) {
+    return { contents: [{ uri: BOARD_URI, mimeType: UI_MIME, text: buildBoardPage(), _meta: { ui: resourceMeta() } }] };
+  }
+  if (typeof uri === 'string' && uri.startsWith(VENDOR_PREFIX)) {
+    const name = uri.slice(VENDOR_PREFIX.length);
+    const text = vendorText(name);
+    if (text == null) { const e = new Error('vendor not found: ' + name); e.code = -32002; throw e; }
+    return { contents: [{ uri, mimeType: 'application/javascript', text }] };
+  }
+  const e = new Error('resource not found: ' + uri);
+  e.code = -32002;
+  throw e;
+}
+// A tool call: normalize the spec and hand it to the host as structuredContent.
+// The host renders ui://relay/board and forwards this spec to the iframe, which
+// collects the answers and returns them via ui/update-model-context. Spec errors
+// come back as an isError tool result (not a protocol error) so the model can
+// see and fix them.
+function callTool(params) {
+  const name = params && params.name;
+  if (name !== 'relay_ask' && name !== 'relay_show') {
+    return { content: [{ type: 'text', text: 'unknown tool: ' + name }], isError: true };
+  }
+  const args = (params && params.arguments && typeof params.arguments === 'object') ? params.arguments : {};
+  let spec;
+  try {
+    spec = normalizeSpec(args);
+  } catch (err) {
+    const msg = err instanceof CliError ? err.message : String((err && err.message) || err);
+    return { content: [{ type: 'text', text: 'relay: invalid board spec — ' + msg }], isError: true };
+  }
+  const nQ = spec.questions.length;
+  const summary = nQ
+    ? `Relay board "${spec.title}" is now displayed to the user (${nQ} question${nQ === 1 ? '' : 's'}). They will fill it in and submit; their answers will be delivered back to you. Do NOT re-ask these questions in plain text — wait for the submission.`
+    : `Relay board "${spec.title}" is now displayed to the user. They can review it and acknowledge; any feedback will be delivered back to you.`;
+  return {
+    content: [{ type: 'text', text: summary }],
+    structuredContent: { spec, mode: name === 'relay_show' ? 'show' : 'ask' },
+    _meta: { ui: { resourceUri: BOARD_URI }, [UI_EXT]: { resourceUri: BOARD_URI } },
+  };
+}
+// ---------- stdio loop ----------
+export function runMcp() {
+  // The peer closing stdout (EPIPE) is the only reason to stop writing — NOT a
+  // `false` return from write(), which just signals backpressure (the 145KB
+  // board page reliably triggers it). Honoring backpressure as "stop" would
+  // silently drop every response after a large one.
+  let stdoutOpen = true;
+  process.stdout.on('error', () => { stdoutOpen = false; });
+  const send = (obj) => {
+    if (!stdoutOpen) return;
+    try { process.stdout.write(JSON.stringify(obj) + '\n'); }
+    catch { stdoutOpen = false; }
+  };
+  function handleLine(line) {
+    let msg;
+    try { msg = JSON.parse(line); } catch {
+      send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
+      return;
+    }
+    const messages = Array.isArray(msg) ? msg : [msg];
+    for (const m of messages) {
+      if (!m || typeof m !== 'object') continue;
+      const isRequest = m.id !== undefined && m.id !== null && typeof m.method === 'string';
+      if (typeof m.method !== 'string') continue; // a response to us — we issue none
+      let result;
+      try {
+        result = buildResult(m.method, m.params || {});
+      } catch (err) {
+        if (isRequest) {
+          send({ jsonrpc: '2.0', id: m.id, error: { code: err.code || -32603, message: err.message || String(err) } });
+        }
+        continue;
+      }
+      if (isRequest) send({ jsonrpc: '2.0', id: m.id, result });
+    }
+  }
+  let buf = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => {
+    buf += chunk;
+    let idx;
+    while ((idx = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, idx);
+      buf = buf.slice(idx + 1);
+      const trimmed = line.trim();
+      if (trimmed) handleLine(trimmed);
+    }
+  });
+  // Resolve only when the input stream closes (host disconnected). Returning a
+  // promise that stays pending keeps the CLI's post-run exit timer from firing.
+  return new Promise((resolve) => {
+    const finish = () => resolve(0);
+    process.stdin.on('end', finish);
+    process.stdin.on('close', finish);
+    process.on('SIGINT', finish);
+    process.on('SIGTERM', finish);
+  });
+}
+// ---------- Streamable HTTP transport ----------
+// `rly mcp --http` serves the SAME server over MCP's Streamable HTTP transport
+// instead of stdio, so a host that connects over the network (Claude web/mobile,
+// a remote/custom connector) can render relay boards — not just a local desktop
+// host. relay is stateless (each tools/call is self-contained and the board
+// state lives in the iframe), so every POST is routed through buildResult and
+// answered with a single application/json response; we never need SSE.
+//
+//   • POST <endpoint>  — one JSON-RPC request → one JSON response; a
+//                        notification/response → 202 Accepted.
+//   • GET  <endpoint>  — 405 (we open no server→client stream).
+//   • DELETE           — 200 (no session state to drop).
+//   • OPTIONS          — CORS preflight (never auth-gated).
+//
+// Security per the transport spec: bind to localhost by default, validate the
+// Origin header (localhost only unless --allow-origin opts in), and support an
+// optional bearer token for an exposed endpoint.
+const HTTP_PATH = '/mcp';
+const MAX_BODY = 16 * 1024 * 1024;
+function corsHeaders(origin) {
+  return {
+    'access-control-allow-origin': origin || '*',
+    'access-control-allow-methods': 'GET, POST, DELETE, OPTIONS',
+    'access-control-allow-headers': 'content-type, authorization, mcp-session-id, mcp-protocol-version, last-event-id',
+    'access-control-expose-headers': 'Mcp-Session-Id',
+    'access-control-max-age': '86400',
+    vary: 'Origin',
+  };
+}
+function originAllowed(origin, allowOrigin) {
+  if (!origin) return true; // non-browser client sends no Origin
+  if (allowOrigin === '*') return true;
+  if (allowOrigin && origin === allowOrigin) return true;
+  try {
+    const h = new URL(origin).hostname;
+    return h === 'localhost' || h === '127.0.0.1' || h === '::1';
+  } catch {
+    return false;
+  }
+}
+function safeEqual(a, b) {
+  const A = Buffer.from(String(a));
+  const B = Buffer.from(String(b));
+  if (A.length !== B.length) return false;
+  try { return crypto.timingSafeEqual(A, B); } catch { return false; }
+}
+function healthPage(endpoint) {
+  return (
+    '<!doctype html><meta charset="utf-8"><title>relay MCP</title>' +
+    '<style>body{font:15px/1.6 -apple-system,system-ui,sans-serif;max-width:640px;margin:14vh auto;padding:0 20px;color:#1c1b19;background:#fcfbf9}' +
+    'code{background:#f1efe8;padding:2px 6px;border-radius:5px;font-size:13px}h1{color:#c2674b;font-size:20px}</style>' +
+    '<h1>relay · MCP Apps server</h1>' +
+    '<p>This is relay running over the <b>Streamable HTTP</b> MCP transport. Point an MCP host at the endpoint below and call <code>relay_ask</code> / <code>relay_show</code>.</p>' +
+    '<p>MCP endpoint: <code>' + escapeHtml(endpoint) + '</code></p>' +
+    '<p>It speaks JSON-RPC over HTTP POST — open it in a browser and you get this page; an MCP client gets the protocol.</p>'
+  );
+}
+export function runMcpHttp({ port = DEFAULT_HTTP_PORT, host = '127.0.0.1', token = '', allowOrigin = '' } = {}) {
+  const requireAuth = Boolean(token);
+  const server = http.createServer((req, res) => {
+    const origin = req.headers.origin || '';
+    const url = (req.url || '/').split('?')[0];
+    const base = corsHeaders(origin);
+    if (req.method === 'OPTIONS') {
+      if (!originAllowed(origin, allowOrigin)) { res.writeHead(403); return res.end(); }
+      res.writeHead(204, base); return res.end();
+    }
+    // Health page only at GET / — POST / is still accepted as the MCP endpoint.
+    if (req.method === 'GET' && url === '/') {
+      res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      return res.end(healthPage(`http://${host === '0.0.0.0' ? 'localhost' : host}:${port}${HTTP_PATH}`));
+    }
+    if (url !== HTTP_PATH && url !== '/') { res.writeHead(404, base); return res.end('not found'); }
+    if (!originAllowed(origin, allowOrigin)) { res.writeHead(403, base); return res.end('origin not allowed'); }
+    if (req.method === 'GET') { res.writeHead(405, { ...base, allow: 'POST, DELETE, OPTIONS' }); return res.end(); }
+    if (req.method === 'DELETE') { res.writeHead(200, { ...base, 'content-type': 'application/json' }); return res.end('{}'); }
+    if (req.method !== 'POST') { res.writeHead(405, { ...base, allow: 'POST, DELETE, OPTIONS' }); return res.end(); }
+    if (requireAuth) {
+      const auth = req.headers.authorization || '';
+      if (!(auth.startsWith('Bearer ') && safeEqual(auth.slice(7), token))) {
+        res.writeHead(401, { ...base, 'www-authenticate': 'Bearer' }); return res.end('unauthorized');
+      }
+    }
+    let body = '';
+    let aborted = false;
+    req.on('data', (c) => { body += c; if (body.length > MAX_BODY) { aborted = true; req.destroy(); } });
+    req.on('end', () => {
+      if (aborted) { res.writeHead(413, base); return res.end(); }
+      let msg;
+      try { msg = JSON.parse(body); } catch {
+        res.writeHead(400, { ...base, 'content-type': 'application/json' });
+        return res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } }));
+      }
+      const list = Array.isArray(msg) ? msg : [msg];
+      const responses = [];
+      let isInit = false;
+      for (const m of list) {
+        if (!m || typeof m !== 'object' || typeof m.method !== 'string') continue;
+        if (m.method === 'initialize') isInit = true;
+        const isRequest = m.id !== undefined && m.id !== null;
+        try {
+          const result = buildResult(m.method, m.params || {});
+          if (isRequest) responses.push({ jsonrpc: '2.0', id: m.id, result });
+        } catch (err) {
+          if (isRequest) responses.push({ jsonrpc: '2.0', id: m.id, error: { code: err.code || -32603, message: err.message || String(err) } });
+        }
+      }
+      if (!responses.length) { res.writeHead(202, base); return res.end(); } // notifications/responses only
+      const headers = { ...base, 'content-type': 'application/json; charset=utf-8' };
+      if (isInit) headers['mcp-session-id'] = crypto.randomUUID();
+      res.writeHead(200, headers);
+      res.end(JSON.stringify(Array.isArray(msg) ? responses : responses[0]));
+    });
+    req.on('error', () => { try { res.writeHead(400, base); res.end(); } catch { /* already gone */ } });
+  });
+  return new Promise((resolve) => {
+    server.on('error', (e) => { process.stderr.write('relay mcp http error: ' + ((e && e.message) || e) + '\n'); resolve(1); });
+    server.listen(port, host, () => {
+      const shown = host === '0.0.0.0' ? 'localhost' : host;
+      process.stderr.write(`relay MCP (Streamable HTTP) listening on http://${shown}:${port}${HTTP_PATH}\n`);
+      if (!requireAuth && host !== '127.0.0.1' && host !== 'localhost') {
+        process.stderr.write('  warning: bound to a non-local interface with no --token — anyone who can reach this port can drive relay.\n');
+      }
+    });
+    const stop = () => { try { server.close(); } catch { /* noop */ } resolve(0); };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+  });
+}
+// The setup snippet printed by `rly mcp config` / `rly mcp install --print`.
+// Returns { json, toml, paths } so the CLI can present per-host instructions.
+export function mcpConfig({ command = 'rly', httpPort = DEFAULT_HTTP_PORT } = {}) {
+  return {
+    command,
+    args: ['mcp'],
+    httpPort,
+    httpUrl: `http://127.0.0.1:${httpPort}${HTTP_PATH}`,
+    // Claude Desktop / generic MCP JSON config (claude_desktop_config.json,
+    // .mcp.json, VS Code mcp.json, …).
+    json: {
+      mcpServers: {
+        relay: { command, args: ['mcp'] },
+      },
+    },
+    // Codex CLI (~/.codex/config.toml).
+    toml: `[mcp_servers.relay]\ncommand = "${command}"\nargs = ["mcp"]\n`,
+    // Remote / web+mobile hosts (Claude web/mobile custom connector, etc.):
+    // run `rly mcp --http` somewhere reachable and register the URL.
+    http: {
+      run: `${command} mcp --http --port ${httpPort}`,
+      url: `http://127.0.0.1:${httpPort}${HTTP_PATH}`,
+      note: 'For web/mobile, expose this URL (e.g. a cloudflared/ngrok tunnel) and add it as a custom connector. Use --token <secret> + --allow-origin <host> when exposing it publicly.',
+    },
+  };
+}

package/src/spec.js CHANGED Viewed

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { CliError } from './util.js';
-export const TYPES = ['single', 'multi', 'yesno', 'text', 'textarea', 'scale'];
+export const TYPES = ['single', 'multi', 'yesno', 'text', 'textarea', 'scale', 'color'];
 const ALIASES = {
   radio: 'single',
@@ -19,13 +19,15 @@ const ALIASES = {
   long: 'textarea',
   rating: 'scale',
   likert: 'scale',
+  colour: 'color',
+  swatch: 'color',
 };
 const HTML_HEIGHT = { min: 100, max: 2400, boardDefault: 400, questionDefault: 360 };
 // Block heights clamp to the same window; defaults vary per block type.
 const BLOCK_HEIGHT = { min: 100, max: 2400 };
-export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'diff', 'video', 'html', 'image'];
+export const BLOCK_TYPES = ['markdown', 'mermaid', 'graphviz', 'plantuml', 'chart', 'table', 'code', 'diff', 'video', 'html', 'image', 'palette'];
 const CHART_KINDS = ['bar', 'line', 'pie', 'doughnut', 'radar', 'scatter'];
 // code/diff blocks may load their text from a local file (like htmlFile). Caps
@@ -360,6 +362,37 @@ function normalizeBlock(rawBlock, id, cwd, where) {
     return block;
   }
+  if (type === 'palette') {
+    // Accept either { palettes: [{name, colors:[…]}, …] } or a single-palette
+    // shorthand { name?, colors:[…] }. Each palette needs a non-empty colors
+    // array of CSS color strings (#rrggbb, rgb(), hsl(), named — kept as given).
+    const rawList = Array.isArray(rawBlock.palettes)
+      ? rawBlock.palettes
+      : (Array.isArray(rawBlock.colors) ? [{ name: rawBlock.name, sub: rawBlock.sub, colors: rawBlock.colors }] : null);
+    if (!rawList || !rawList.length) {
+      throw new CliError(`${where}: palette block needs "palettes" (array) or a "colors" array.`);
+    }
+    const palettes = rawList.map((p, j) => {
+      if (!p || typeof p !== 'object') throw new CliError(`${where}.palettes[${j}]: must be an object with "colors".`);
+      const colors = (Array.isArray(p.colors) ? p.colors : [])
+        .map((c) => asStr(c).trim())
+        .filter(Boolean);
+      if (!colors.length) throw new CliError(`${where}.palettes[${j}]: needs a non-empty "colors" array.`);
+      const out = { colors };
+      if (p.name !== undefined) out.name = asStr(p.name);
+      const sub = p.sub ?? p.mood;
+      if (sub !== undefined) out.sub = asStr(sub);
+      const tag = p.badge ?? p.tag;
+      if (tag !== undefined) out.tag = asStr(tag);
+      if (p.tagTone !== undefined) out.tagTone = asStr(p.tagTone).trim().toLowerCase();
+      if (p.featured === true) out.featured = true;
+      return out;
+    });
+    const block = { id, type: 'palette', palettes };
+    if (rawBlock.title !== undefined) block.title = asStr(rawBlock.title);
+    return block;
+  }
   // type === 'html'
   const html = readBlockHtml(rawBlock, cwd, where);
   if (!html) {
@@ -487,6 +520,14 @@ export function normalizeSpec(raw, { cwd = process.cwd() } = {}) {
       q.maxLabel = asStr(rq.maxLabel);
     }
+    if (type === 'color') {
+      // Optional preset swatches the user can click beside the native picker.
+      const presets = (Array.isArray(rq.presets) ? rq.presets : [])
+        .map((c) => asStr(c).trim())
+        .filter(Boolean);
+      if (presets.length) q.presets = presets;
+    }
     if (rq.default !== undefined) q.default = rq.default;
     spec.questions.push(q);
   });
@@ -555,6 +596,26 @@ const BLOCK_SCHEMA = {
       htmlFile: { type: 'string', description: 'html: path to an HTML file (alternative to "html").' },
       src: { type: 'string', description: 'image: http(s)/data URL, or a local file path (png/jpg/gif/webp/svg/avif/bmp — embedded at spec time, served offline). video: a YouTube/Vimeo URL (embeds an iframe player), an http(s) media URL, or a local video file (mp4/webm/ogv/mov/mkv/m4v — streamed from the server, never embedded).' },
       alt: { type: 'string', description: 'image: alt text / annotation label. video: accessible title for the player.' },
+      palettes: {
+        type: 'array',
+        description: 'palette: one or more color palettes to display as swatch cards. Each swatch reveals its hex on hover and copies it on click; mark one {featured:true} to show it as a larger spotlight. Each item: {name?, sub? (or mood?), tag? (or badge?), tagTone? (warm|cool|neutral|nature|bold|digital), featured?, colors:[…]}.',
+        items: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            sub: { type: 'string' },
+            mood: { type: 'string' },
+            tag: { type: 'string' },
+            badge: { type: 'string' },
+            tagTone: { type: 'string', enum: ['warm', 'cool', 'neutral', 'nature', 'bold', 'digital'] },
+            featured: { type: 'boolean' },
+            colors: { type: 'array', items: { type: 'string' }, description: 'CSS colors — #rrggbb, rgb()/hsl(), or named.' },
+          },
+          required: ['colors'],
+        },
+      },
+      colors: { type: 'array', items: { type: 'string' }, description: 'palette shorthand: colors for a single palette (use "palettes" for several named ones). Pairs with block-level "name".' },
+      name: { type: 'string', description: 'palette shorthand: name for the single "colors" palette.' },
       height: { type: 'integer', minimum: BLOCK_HEIGHT.min, maximum: BLOCK_HEIGHT.max, description: 'Block height in px. Defaults: chart 320, html 360; markdown/table/code flow naturally; mermaid/graphviz/plantuml/image natural (max 1200, scrolls).' },
     },
   },
@@ -584,7 +645,7 @@ export const SPEC_SCHEMA = {
         required: ['label'],
         properties: {
           id: { type: 'string', description: 'Answer key in the result JSON. Defaults to q1, q2, …' },
-          type: { type: 'string', enum: ['single', 'multi', 'yesno', 'text', 'textarea', 'scale'], default: 'text' },
+          type: { type: 'string', enum: ['single', 'multi', 'yesno', 'text', 'textarea', 'scale', 'color'], default: 'text' },
           label: { type: 'string' },
           description: { type: 'string' },
           required: { type: 'boolean', default: false },
@@ -614,6 +675,7 @@ export const SPEC_SCHEMA = {
           max: { type: 'integer', default: 5, maximum: 10, description: 'scale only' },
           minLabel: { type: 'string', description: 'scale only' },
           maxLabel: { type: 'string', description: 'scale only' },
+          presets: { type: 'array', items: { type: 'string' }, description: 'color only: optional preset swatches (CSS colors) shown beside the native picker for one-click selection. The answer is returned as a hex string.' },
           blocks: BLOCK_SCHEMA,
           html: { type: 'string', description: 'Legacy: per-question custom HTML. Normalized into an html block prepended to this question\'s "blocks".' },
           htmlFile: { type: 'string', description: 'Legacy: path to an HTML file (alternative to "html").' },

package/src/ui/app.js CHANGED Viewed

@@ -698,6 +698,38 @@
     return input;
   }
+  // Normalize any CSS color to the #rrggbb the native <input type=color> needs.
+  function toHex6(c) {
+    const s = String(c || '').trim();
+    let m = /^#?([0-9a-fA-F]{6})$/.exec(s);
+    if (m) return '#' + m[1].toLowerCase();
+    m = /^#?([0-9a-fA-F]{3})$/.exec(s);
+    if (m) return '#' + m[1].split('').map((x) => x + x).join('').toLowerCase();
+    return '#000000';
+  }
+  function controlColor(q) {
+    const wrap = el('div', { class: 'colorpick' });
+    const init = (typeof state.answers[q.id] === 'string' && state.answers[q.id]) || (typeof q.default === 'string' ? q.default : '');
+    const swatch = el('input', { type: 'color', class: 'colorswatch' });
+    const hex = el('input', { type: 'text', class: 'colorhex', placeholder: q.placeholder || '#rrggbb', spellcheck: 'false', autocapitalize: 'off' });
+    swatch.value = toHex6(init || '#888888');
+    if (init) { hex.value = init; state.answers[q.id] = init; }
+    const set = (val) => { state.answers[q.id] = val; clearErr(q.id); scheduleSave(); };
+    swatch.addEventListener('input', () => { hex.value = swatch.value; set(swatch.value); });
+    hex.addEventListener('input', () => { const v = hex.value.trim(); if (/^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(v)) swatch.value = toHex6(v); set(v); });
+    wrap.append(el('div', { class: 'colorrow' }, swatch, hex));
+    if (Array.isArray(q.presets) && q.presets.length) {
+      const presets = el('div', { class: 'colorpresets' });
+      for (const c of q.presets) {
+        const b = el('button', { type: 'button', class: 'colorpreset', style: 'background:' + c, title: c });
+        b.addEventListener('click', () => { swatch.value = toHex6(c); hex.value = c; set(c); });
+        presets.append(b);
+      }
+      wrap.append(presets);
+    }
+    return wrap;
+  }
   // ---------- render ----------
   themeBtn = el('button', { class: 'theme-btn', type: 'button' }, '');
   themeBtn.addEventListener('click', () => {
@@ -757,6 +789,7 @@
     else if (q.type === 'multi') control.append(controlMulti(q));
     else if (q.type === 'yesno') control.append(segButtons(q, ['yes', 'no'], ['Yes', 'No']));
     else if (q.type === 'scale') control.append(controlScale(q));
+    else if (q.type === 'color') control.append(controlColor(q));
     else control.append(controlText(q, q.type === 'textarea'));
     card.append(control);
     if (q.note) {