clawport-ui 0.1.0

package/lib/sanitize.ts

@@ -0,0 +1,194 @@
+/**
+ * HTML sanitization and safe markdown rendering utilities.
+ *
+ * Design:
+ * - escapeHtml() handles the 5 critical HTML special characters
+ * - MarkdownRenderer is a configurable pipeline: escape first, then transform
+ * - Open/Closed: add new renderers via the `rules` array without modifying core
+ * - Dependency Inversion: consumers depend on the MarkdownRule interface, not
+ *   a specific implementation
+ */
+
+// ---------------------------------------------------------------------------
+// Core escape function
+// ---------------------------------------------------------------------------
+
+const HTML_ESCAPE_MAP: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#x27;",
+};
+
+const HTML_ESCAPE_RE = /[&<>"']/g;
+
+/**
+ * Escape all HTML-significant characters so that the string is safe
+ * to embed inside an HTML document (both element content and attributes).
+ */
+export function escapeHtml(text: string): string {
+  return text.replace(HTML_ESCAPE_RE, (ch) => HTML_ESCAPE_MAP[ch]);
+}
+
+// ---------------------------------------------------------------------------
+// Markdown rendering pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * A single markdown-to-HTML transformation rule.
+ * Rules are applied in order after the input has already been HTML-escaped.
+ */
+export interface MarkdownRule {
+  /** Human-readable name for debugging / extensibility */
+  name: string;
+  /** Regex to match against the escaped text */
+  pattern: RegExp;
+  /** Replacement string (may use $1, $2, etc.) */
+  replacement: string;
+}
+
+/** Default rules that ship with the renderer. */
+export const DEFAULT_MARKDOWN_RULES: MarkdownRule[] = [
+  {
+    name: "h4",
+    pattern: /^#### (.+)$/gm,
+    replacement:
+      '<h4 class="text-[15px] font-semibold" style="color:var(--text-primary);margin-top:1rem;margin-bottom:0.25rem">$1</h4>',
+  },
+  {
+    name: "h3",
+    pattern: /^### (.+)$/gm,
+    replacement:
+      '<h3 class="text-[17px] font-semibold" style="color:var(--text-primary);margin-top:1.25rem;margin-bottom:0.375rem">$1</h3>',
+  },
+  {
+    name: "h2",
+    pattern: /^## (.+)$/gm,
+    replacement:
+      '<h2 class="text-[22px] font-semibold" style="color:var(--text-primary);margin-top:1.5rem;margin-bottom:0.5rem;padding-bottom:0.25rem;border-bottom:1px solid var(--separator)">$1</h2>',
+  },
+  {
+    name: "h1",
+    pattern: /^# (.+)$/gm,
+    replacement:
+      '<h1 class="text-[28px] font-bold" style="color:var(--text-primary);margin-top:1rem;margin-bottom:0.75rem">$1</h1>',
+  },
+  {
+    name: "bold",
+    pattern: /\*\*(.+?)\*\*/g,
+    replacement:
+      '<strong class="font-semibold" style="color:var(--text-primary)">$1</strong>',
+  },
+  {
+    name: "inline-code",
+    pattern: /`([^`]+)`/g,
+    replacement:
+      '<code style="background:var(--fill-secondary);color:var(--accent);padding:2px 6px;border-radius:6px;font-size:13px;font-family:var(--font-mono)">$1</code>',
+  },
+  {
+    name: "unordered-list",
+    pattern: /^- (.+)$/gm,
+    replacement:
+      '<li class="ml-4 text-[15px] leading-[1.7] list-disc" style="color:var(--text-secondary)">$1</li>',
+  },
+  {
+    name: "ordered-list",
+    pattern: /^(\d+)\. (.+)$/gm,
+    replacement:
+      '<li class="ml-4 text-[15px] leading-[1.7] list-decimal" style="color:var(--text-secondary)">$2</li>',
+  },
+  {
+    name: "paragraph-break",
+    pattern: /\n{2,}/g,
+    replacement:
+      '</p><p class="mb-3" style="color:var(--text-secondary)">',
+  },
+  {
+    name: "line-break",
+    pattern: /\n/g,
+    replacement: "<br/>",
+  },
+];
+
+export interface MarkdownRendererOptions {
+  /** Override or extend the default rules */
+  rules?: MarkdownRule[];
+}
+
+/**
+ * Render a plain-text markdown string to safe HTML.
+ *
+ * The pipeline is:
+ *   1. Escape ALL HTML entities (neutralises any injected markup)
+ *   2. Apply markdown transformation rules in order
+ *
+ * Because escaping happens first, captured groups ($1 etc.) only ever
+ * contain escaped text — no raw HTML can slip through.
+ */
+export function renderMarkdown(
+  text: string,
+  options?: MarkdownRendererOptions
+): string {
+  const rules = options?.rules ?? DEFAULT_MARKDOWN_RULES;
+
+  // Step 1 — escape (this is the security boundary)
+  let html = escapeHtml(text);
+
+  // Step 2 — apply markdown transformations on the safe string
+  for (const rule of rules) {
+    html = html.replace(rule.pattern, rule.replacement);
+  }
+
+  return html;
+}
+
+// ---------------------------------------------------------------------------
+// JSON colorizer (safe)
+// ---------------------------------------------------------------------------
+
+/** Default rules for JSON syntax highlighting (applied after escaping). */
+export const JSON_COLORIZE_RULES: MarkdownRule[] = [
+  {
+    name: "json-key",
+    pattern: /&quot;((?:(?!&quot;).)*?)&quot;(?=\s*:)/g,
+    replacement:
+      '<span style="color:var(--accent)">&quot;$1&quot;</span>',
+  },
+  {
+    name: "json-string-value",
+    pattern: /:\s*&quot;((?:(?!&quot;).)*?)&quot;/g,
+    replacement:
+      ': <span style="color:var(--system-green)">&quot;$1&quot;</span>',
+  },
+  {
+    name: "json-number",
+    pattern: /:\s*(\d+\.?\d*)/g,
+    replacement: ': <span style="color:var(--system-blue)">$1</span>',
+  },
+  {
+    name: "json-boolean",
+    pattern: /:\s*(true|false)/g,
+    replacement: ': <span style="color:#bf5af2">$1</span>',
+  },
+  {
+    name: "json-null",
+    pattern: /:\s*(null)/g,
+    replacement:
+      ': <span style="color:var(--text-tertiary)">$1</span>',
+  },
+];
+
+/**
+ * Syntax-highlight a JSON string safely.
+ * Escapes HTML first, then applies colorization rules.
+ */
+export function colorizeJson(json: string): string {
+  let html = escapeHtml(json);
+
+  for (const rule of JSON_COLORIZE_RULES) {
+    html = html.replace(rule.pattern, rule.replacement);
+  }
+
+  return html;
+}

package/lib/settings.test.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { loadSettings, saveSettings, hexToAccentFill } from './settings'
+
+// Mock localStorage
+const store: Record<string, string> = {}
+const localStorageMock = {
+  getItem: vi.fn((key: string) => store[key] ?? null),
+  setItem: vi.fn((key: string, value: string) => {
+    store[key] = value
+  }),
+  removeItem: vi.fn((key: string) => {
+    delete store[key]
+  }),
+  clear: vi.fn(() => {
+    Object.keys(store).forEach((k) => delete store[k])
+  }),
+}
+Object.defineProperty(globalThis, 'localStorage', { value: localStorageMock })
+
+beforeEach(() => {
+  localStorageMock.clear()
+  vi.clearAllMocks()
+})
+
+describe('loadSettings', () => {
+  it('returns defaults when nothing is stored', () => {
+    const s = loadSettings()
+    expect(s).toEqual({
+      accentColor: null,
+      portalName: null,
+      portalSubtitle: null,
+      portalEmoji: null,
+      portalIcon: null,
+      iconBgHidden: false,
+      emojiOnly: false,
+      operatorName: null,
+      agentOverrides: {},
+    })
+  })
+
+  it('parses stored settings correctly', () => {
+    store['clawport-settings'] = JSON.stringify({
+      accentColor: '#3B82F6',
+      portalName: 'HQ',
+      portalSubtitle: 'Base',
+      portalEmoji: '🚀',
+      portalIcon: 'data:image/jpeg;base64,icon123',
+      agentOverrides: { jarvis: { emoji: '🎯' } },
+    })
+    const s = loadSettings()
+    expect(s.accentColor).toBe('#3B82F6')
+    expect(s.portalName).toBe('HQ')
+    expect(s.portalSubtitle).toBe('Base')
+    expect(s.portalEmoji).toBe('🚀')
+    expect(s.portalIcon).toBe('data:image/jpeg;base64,icon123')
+    expect(s.agentOverrides.jarvis).toEqual({ emoji: '🎯' })
+  })
+
+  it('returns defaults for invalid JSON', () => {
+    store['clawport-settings'] = 'not-json{{'
+    const s = loadSettings()
+    expect(s.accentColor).toBeNull()
+    expect(s.agentOverrides).toEqual({})
+  })
+
+  it('handles partial/malformed data gracefully', () => {
+    store['clawport-settings'] = JSON.stringify({
+      accentColor: 42,
+      portalName: true,
+      agentOverrides: 'not-an-object',
+    })
+    const s = loadSettings()
+    expect(s.accentColor).toBeNull()
+    expect(s.portalName).toBeNull()
+    expect(s.portalEmoji).toBeNull()
+    expect(s.portalIcon).toBeNull()
+    expect(s.agentOverrides).toEqual({})
+  })
+})
+
+describe('saveSettings', () => {
+  it('persists settings to localStorage', () => {
+    const settings = {
+      accentColor: '#EF4444',
+      portalName: 'Test',
+      portalSubtitle: null,
+      portalEmoji: null,
+      portalIcon: null,
+      iconBgHidden: false,
+      emojiOnly: false,
+      operatorName: null,
+      agentOverrides: {},
+    }
+    saveSettings(settings)
+    expect(localStorageMock.setItem).toHaveBeenCalledWith(
+      'clawport-settings',
+      JSON.stringify(settings),
+    )
+  })
+
+  it('round-trips through load', () => {
+    const settings = {
+      accentColor: '#22C55E',
+      portalName: 'Green HQ',
+      portalSubtitle: 'Ops Center',
+      portalEmoji: '🏠',
+      portalIcon: 'data:image/png;base64,test',
+      iconBgHidden: false,
+      emojiOnly: false,
+      operatorName: null,
+      agentOverrides: {
+        vera: { emoji: '🧙', profileImage: 'data:image/jpeg;base64,abc' },
+      },
+    }
+    saveSettings(settings)
+    const loaded = loadSettings()
+    expect(loaded).toEqual(settings)
+  })
+})
+
+describe('hexToAccentFill', () => {
+  it('converts gold hex to rgba at 0.15 alpha', () => {
+    expect(hexToAccentFill('#F5C518')).toBe('rgba(245,197,24,0.15)')
+  })
+
+  it('converts blue hex correctly', () => {
+    expect(hexToAccentFill('#3B82F6')).toBe('rgba(59,130,246,0.15)')
+  })
+
+  it('converts black hex correctly', () => {
+    expect(hexToAccentFill('#000000')).toBe('rgba(0,0,0,0.15)')
+  })
+
+  it('converts white hex correctly', () => {
+    expect(hexToAccentFill('#FFFFFF')).toBe('rgba(255,255,255,0.15)')
+  })
+})

package/lib/settings.ts

@@ -0,0 +1,94 @@
+// Settings types + localStorage helpers for ClawPort
+
+export interface AgentOverride {
+  emoji?: string
+  profileImage?: string // base64 data URL
+}
+
+export interface ClawPortSettings {
+  accentColor: string | null
+  portalName: string | null
+  portalSubtitle: string | null
+  portalEmoji: string | null
+  portalIcon: string | null // base64 data URL for custom icon image
+  iconBgHidden: boolean // hide colored background on sidebar logo
+  emojiOnly: boolean // show emoji avatars without colored background
+  operatorName: string | null
+  agentOverrides: Record<string, AgentOverride>
+}
+
+const STORAGE_KEY = 'clawport-settings'
+const LEGACY_KEY = 'manor-settings'
+
+export const DEFAULTS: ClawPortSettings = {
+  accentColor: null,
+  portalName: null,
+  portalSubtitle: null,
+  portalEmoji: null,
+  portalIcon: null,
+  iconBgHidden: false,
+  emojiOnly: false,
+  operatorName: null,
+  agentOverrides: {},
+}
+
+export function loadSettings(): ClawPortSettings {
+  if (typeof window === 'undefined') return { ...DEFAULTS }
+  try {
+    let raw = localStorage.getItem(STORAGE_KEY)
+    // Migrate from legacy key
+    if (!raw) {
+      raw = localStorage.getItem(LEGACY_KEY)
+      if (raw) {
+        localStorage.setItem(STORAGE_KEY, raw)
+        localStorage.removeItem(LEGACY_KEY)
+      }
+    }
+    if (!raw) return { ...DEFAULTS }
+    const parsed = JSON.parse(raw)
+    return {
+      accentColor: typeof parsed.accentColor === 'string' ? parsed.accentColor : null,
+      portalName: typeof parsed.portalName === 'string' ? parsed.portalName : typeof parsed.manorName === 'string' ? parsed.manorName : null,
+      portalSubtitle: typeof parsed.portalSubtitle === 'string' ? parsed.portalSubtitle : typeof parsed.manorSubtitle === 'string' ? parsed.manorSubtitle : null,
+      portalEmoji: typeof parsed.portalEmoji === 'string' ? parsed.portalEmoji : typeof parsed.manorEmoji === 'string' ? parsed.manorEmoji : null,
+      portalIcon: typeof parsed.portalIcon === 'string' ? parsed.portalIcon : typeof parsed.manorIcon === 'string' ? parsed.manorIcon : null,
+      iconBgHidden: typeof parsed.iconBgHidden === 'boolean' ? parsed.iconBgHidden : false,
+      emojiOnly: typeof parsed.emojiOnly === 'boolean' ? parsed.emojiOnly : false,
+      operatorName: typeof parsed.operatorName === 'string' ? parsed.operatorName : null,
+      agentOverrides:
+        parsed.agentOverrides && typeof parsed.agentOverrides === 'object'
+          ? parsed.agentOverrides
+          : {},
+    }
+  } catch {
+    return { ...DEFAULTS }
+  }
+}
+
+export function saveSettings(settings: ClawPortSettings): void {
+  if (typeof window === 'undefined') return
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(settings))
+  } catch {}
+}
+
+/** Convert hex color to rgba at 0.15 alpha for accent-fill backgrounds */
+export function hexToAccentFill(hex: string): string {
+  const r = parseInt(hex.slice(1, 3), 16)
+  const g = parseInt(hex.slice(3, 5), 16)
+  const b = parseInt(hex.slice(5, 7), 16)
+  return `rgba(${r},${g},${b},0.15)`
+}
+
+/** Return '#fff' or '#000' depending on which has better contrast against the given hex color */
+export function hexToContrastText(hex: string): string {
+  const r = parseInt(hex.slice(1, 3), 16) / 255
+  const g = parseInt(hex.slice(3, 5), 16) / 255
+  const b = parseInt(hex.slice(5, 7), 16) / 255
+  // sRGB luminance (WCAG 2.0)
+  const lum =
+    0.2126 * (r <= 0.03928 ? r / 12.92 : ((r + 0.055) / 1.055) ** 2.4) +
+    0.7152 * (g <= 0.03928 ? g / 12.92 : ((g + 0.055) / 1.055) ** 2.4) +
+    0.0722 * (b <= 0.03928 ? b / 12.92 : ((b + 0.055) / 1.055) ** 2.4)
+  return lum > 0.4 ? '#000' : '#fff'
+}

package/lib/styles.ts

@@ -0,0 +1,24 @@
+// Semantic style objects for TypeScript components
+// Use when CSS classes aren't practical (dynamic styles)
+
+export const typography = {
+  largeTitle: { fontSize: 'var(--text-large-title)', fontWeight: 'var(--weight-bold)', letterSpacing: 'var(--tracking-tight)', lineHeight: 'var(--leading-tight)' },
+  title1: { fontSize: 'var(--text-title1)', fontWeight: 'var(--weight-bold)', letterSpacing: 'var(--tracking-tight)', lineHeight: 'var(--leading-tight)' },
+  title2: { fontSize: 'var(--text-title2)', fontWeight: 'var(--weight-semibold)', letterSpacing: 'var(--tracking-normal)', lineHeight: 'var(--leading-snug)' },
+  title3: { fontSize: 'var(--text-title3)', fontWeight: 'var(--weight-semibold)', letterSpacing: 'var(--tracking-normal)', lineHeight: 'var(--leading-snug)' },
+  body: { fontSize: 'var(--text-body)', fontWeight: 'var(--weight-regular)', lineHeight: 'var(--leading-normal)' },
+  subheadline: { fontSize: 'var(--text-subheadline)', fontWeight: 'var(--weight-regular)', lineHeight: 'var(--leading-normal)' },
+  footnote: { fontSize: 'var(--text-footnote)', fontWeight: 'var(--weight-regular)', lineHeight: 'var(--leading-normal)' },
+  caption1: { fontSize: 'var(--text-caption1)', fontWeight: 'var(--weight-regular)', lineHeight: 'var(--leading-normal)' },
+  caption2: { fontSize: 'var(--text-caption2)', fontWeight: 'var(--weight-regular)', lineHeight: 'var(--leading-normal)' },
+  sectionHeader: { fontSize: 'var(--text-caption2)', fontWeight: 'var(--weight-semibold)', letterSpacing: 'var(--tracking-wide)', textTransform: 'uppercase' as const, color: 'var(--text-tertiary)' },
+} as const
+
+export const layout = {
+  sidebarWidth: 220,
+  detailPanelWidth: 360,
+  chatSidebarWidth: 300,
+  memorySidebarWidth: 260,
+  maxContentWidth: 1200,
+  headerHeight: 52,
+} as const

package/lib/themes.ts

@@ -0,0 +1,9 @@
+export type ThemeId = 'dark' | 'glass' | 'color' | 'light' | 'system';
+
+export const THEMES: { id: ThemeId; label: string; emoji: string }[] = [
+  { id: 'dark',   label: 'Dark',   emoji: '🌑' },
+  { id: 'glass',  label: 'Glass',  emoji: '🪟' },
+  { id: 'color',  label: 'Color',  emoji: '🎨' },
+  { id: 'light',  label: 'Light',  emoji: '☀️' },
+  { id: 'system', label: 'System', emoji: '⚙️' },
+];

package/lib/transcribe.test.ts

@@ -0,0 +1,141 @@
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { transcribeViaApi, transcribe } from './transcribe'
+
+// --- transcribeViaApi ---
+
+describe('transcribeViaApi', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    globalThis.fetch = vi.fn()
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('returns transcript text on successful API response', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => ({ text: 'hello world' }),
+    })
+
+    const blob = new Blob(['fake audio'], { type: 'audio/webm' })
+    const result = await transcribeViaApi(blob)
+    expect(result).toBe('hello world')
+  })
+
+  it('calls /api/transcribe with POST and FormData', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => ({ text: 'test' }),
+    })
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    await transcribeViaApi(blob)
+
+    expect(globalThis.fetch).toHaveBeenCalledWith(
+      '/api/transcribe',
+      expect.objectContaining({ method: 'POST' })
+    )
+    const callArgs = (globalThis.fetch as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[1].body).toBeInstanceOf(FormData)
+  })
+
+  it('returns null when API returns non-ok response', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: false,
+      status: 500,
+    })
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    const result = await transcribeViaApi(blob)
+    expect(result).toBeNull()
+  })
+
+  it('returns null when API returns empty text', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => ({ text: '' }),
+    })
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    const result = await transcribeViaApi(blob)
+    expect(result).toBeNull()
+  })
+
+  it('returns null when API response has no text field', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => ({ error: 'no transcript' }),
+    })
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    const result = await transcribeViaApi(blob)
+    expect(result).toBeNull()
+  })
+
+  it('returns null on network error', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('Network error'))
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    const result = await transcribeViaApi(blob)
+    expect(result).toBeNull()
+  })
+})
+
+// --- transcribe (orchestrator) ---
+
+describe('transcribe', () => {
+  const originalFetch = globalThis.fetch
+
+  beforeEach(() => {
+    globalThis.fetch = vi.fn()
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+  })
+
+  it('returns whisper source when API transcription succeeds', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => ({ text: 'transcribed text' }),
+    })
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    const result = await transcribe(blob)
+    expect(result).toEqual({ text: 'transcribed text', source: 'whisper' })
+  })
+
+  it('returns failed source when API transcription fails', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: false,
+      status: 500,
+    })
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    const result = await transcribe(blob)
+    expect(result).toEqual({ text: null, source: 'failed' })
+  })
+
+  it('returns failed source on network error', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockRejectedValue(new Error('offline'))
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    const result = await transcribe(blob)
+    expect(result).toEqual({ text: null, source: 'failed' })
+  })
+
+  it('returns failed source when API returns empty text', async () => {
+    ;(globalThis.fetch as ReturnType<typeof vi.fn>).mockResolvedValue({
+      ok: true,
+      json: async () => ({ text: '' }),
+    })
+
+    const blob = new Blob(['audio'], { type: 'audio/webm' })
+    const result = await transcribe(blob)
+    expect(result).toEqual({ text: null, source: 'failed' })
+  })
+})