@polderlabs/bizar 7.0.4 → 8.1.0

package/bizar-dash/src/web/v8/__tests__/theme.test.tsx

@@ -0,0 +1,98 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { ThemeProvider } from '../ui/theme/ThemeProvider.js';
+import { useTheme } from '../ui/theme/useTheme.js';
+import { DensityProvider } from '../ui/theme/DensityProvider.js';
+import { useDensity } from '../ui/theme/useDensity.js';
+import type { ReactNode } from 'react';
+
+function wrapperFactory(mode?: 'light' | 'dark' | 'system') {
+  return ({ children }: { children: ReactNode }) => (
+    <ThemeProvider defaultMode={mode}>
+      <DensityProvider>{children}</DensityProvider>
+    </ThemeProvider>
+  );
+}
+
+describe('ThemeProvider', () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('starts with the given defaultMode', () => {
+    const { result } = renderHook(() => useTheme(), { wrapper: wrapperFactory('dark') });
+    expect(result.current.mode).toBe('dark');
+    expect(result.current.resolved).toBe('dark');
+  });
+
+  it('persists setMode to localStorage', () => {
+    const { result } = renderHook(() => useTheme(), { wrapper: wrapperFactory() });
+    act(() => result.current.setMode('light'));
+    expect(window.localStorage.getItem('bizar:theme')).toBe('light');
+    expect(result.current.mode).toBe('light');
+  });
+
+  it('cycles light → dark → system → light', () => {
+    const { result } = renderHook(() => useTheme(), { wrapper: wrapperFactory('light') });
+    expect(result.current.mode).toBe('light');
+
+    act(() => result.current.cycle());
+    expect(result.current.mode).toBe('dark');
+
+    act(() => result.current.cycle());
+    expect(result.current.mode).toBe('system');
+
+    act(() => result.current.cycle());
+    expect(result.current.mode).toBe('light');
+  });
+
+  it('writes data-theme to documentElement on mount', () => {
+    renderHook(() => useTheme(), { wrapper: wrapperFactory('dark') });
+    expect(document.documentElement.dataset['theme']).toBe('dark');
+  });
+});
+
+describe('DensityProvider', () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+  });
+
+  it('defaults to comfortable', () => {
+    const { result } = renderHook(() => useDensity(), { wrapper: wrapperFactory() });
+    expect(result.current.density).toBe('comfortable');
+  });
+
+  it('toggle flips between comfortable and compact', () => {
+    const { result } = renderHook(() => useDensity(), { wrapper: wrapperFactory() });
+    act(() => result.current.toggle());
+    expect(result.current.density).toBe('compact');
+    expect(window.localStorage.getItem('bizar:density')).toBe('compact');
+
+    act(() => result.current.toggle());
+    expect(result.current.density).toBe('comfortable');
+  });
+
+  it('writes data-density to documentElement', () => {
+    renderHook(() => useDensity(), { wrapper: wrapperFactory() });
+    expect(document.documentElement.dataset['density']).toBe('comfortable');
+  });
+});
+
+describe('hook usage outside provider', () => {
+  it('useTheme throws when used without a provider', () => {
+    // suppress React's error boundary log
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => renderHook(() => useTheme())).toThrow(/ThemeProvider/);
+    spy.mockRestore();
+  });
+
+  it('useDensity throws when used without a provider', () => {
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() => renderHook(() => useDensity())).toThrow(/DensityProvider/);
+    spy.mockRestore();
+  });
+});

package/bizar-dash/src/web/v8/__tests__/useFetch.test.ts

@@ -0,0 +1,92 @@
+/**
+ * v8/__tests__/useFetch.test.ts
+ *
+ * Sprint S10 — Verifies the useFetch + fetcher wiring in jsdom.
+ */
+
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import { renderHook, waitFor } from '@testing-library/react';
+import { fetchJson, FetchError } from '../data/fetcher.js';
+import { useFetch } from '../data/useFetch.js';
+
+describe('fetchJson', () => {
+  const originalFetch = global.fetch;
+  beforeEach(() => {
+    global.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ ok: true }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    ) as unknown as typeof fetch;
+  });
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it('parses JSON on 200', async () => {
+    const data = await fetchJson<{ ok: boolean }>('/api/test');
+    expect(data.ok).toBe(true);
+  });
+
+  it('throws FetchError on 4xx', async () => {
+    global.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ error: 'bad_request', message: 'nope' }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    ) as unknown as typeof fetch;
+    await expect(fetchJson('/api/test')).rejects.toBeInstanceOf(FetchError);
+  });
+
+  it('aborts via AbortSignal', async () => {
+    let aborted = false;
+    global.fetch = vi.fn(async (_url, init) =>
+      new Promise((_, reject) => {
+        const signal = (init as RequestInit | undefined)?.signal;
+        if (signal) {
+          signal.addEventListener('abort', () => {
+            aborted = true;
+            const err = new Error('aborted');
+            err.name = 'AbortError';
+            reject(err);
+          });
+        }
+      }),
+    ) as unknown as typeof fetch;
+    const ctrl = new AbortController();
+    const p = fetchJson('/api/test', { signal: ctrl.signal });
+    ctrl.abort();
+    await expect(p).rejects.toThrow();
+    expect(aborted).toBe(true);
+  });
+});
+
+describe('useFetch', () => {
+  beforeEach(() => {
+    global.fetch = vi.fn(async () =>
+      new Response(JSON.stringify({ tasks: [] }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      }),
+    ) as unknown as typeof fetch;
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns loading → data', async () => {
+    const { result } = renderHook(() => useFetch<{ tasks: unknown[] }>('/api/tasks'));
+    await waitFor(() => expect(result.current.loading).toBe(false));
+    expect(result.current.data?.tasks).toEqual([]);
+    expect(result.current.error).toBeNull();
+  });
+
+  it('surfaces error on failure', async () => {
+    global.fetch = vi.fn(async () =>
+      new Response('boom', { status: 500 }),
+    ) as unknown as typeof fetch;
+    const { result } = renderHook(() => useFetch('/api/test'));
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+    expect(result.current.loading).toBe(false);
+  });
+});

package/bizar-dash/src/web/v8/__tests__/useWebSocket.test.ts

@@ -0,0 +1,87 @@
+/**
+ * v8/__tests__/useWebSocket.test.ts
+ *
+ * Sprint S10 — Verifies the WS subscriber wiring in jsdom.
+ */
+
+import { describe, expect, it, beforeEach, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useWsMessages, useWsMessage, _resetForTests } from '../data/useWebSocket.js';
+
+class FakeSocket {
+  readyState = 0;
+  listeners: Record<string, Array<(ev: unknown) => void>> = {};
+  addEventListener(name: string, cb: (ev: unknown) => void) {
+    (this.listeners[name] ||= []).push(cb);
+  }
+  removeEventListener() { /* no-op */ }
+  fire(name: string, ev: unknown) {
+    for (const cb of this.listeners[name] || []) cb(ev);
+  }
+  close() { this.readyState = 3; this.fire('close', {}); }
+  // unused
+  send() {}
+}
+
+let fakeSocket: FakeSocket | null = null;
+
+beforeEach(() => {
+  _resetForTests();
+  fakeSocket = new FakeSocket();
+  // @ts-expect-error -- substitute a fake WebSocket for the singleton.
+  global.WebSocket = class {
+    constructor() { return fakeSocket!; }
+    static OPEN = 1;
+    static CONNECTING = 0;
+    static CLOSED = 3;
+    readyState = 0;
+    addEventListener = fakeSocket!.addEventListener.bind(fakeSocket!);
+    close = fakeSocket!.close.bind(fakeSocket!);
+  };
+});
+
+describe('useWsMessages', () => {
+  it('subscribes and forwards matching messages', () => {
+    const cb = vi.fn();
+    renderHook(() => useWsMessages(cb));
+    // open then message.
+    fakeSocket!.fire('open', {});
+    fakeSocket!.fire('message', { data: JSON.stringify({ type: 'tasks:change', task: { id: 't1' } }) });
+    expect(cb).toHaveBeenCalledWith(expect.objectContaining({ type: 'tasks:change' }));
+  });
+
+  it('unmount removes the listener', () => {
+    const cb = vi.fn();
+    const { unmount } = renderHook(() => useWsMessages(cb));
+    unmount();
+    fakeSocket!.fire('message', { data: JSON.stringify({ type: 'tasks:change' }) });
+    expect(cb).not.toHaveBeenCalled();
+  });
+});
+
+describe('useWsMessage', () => {
+  it('filters by single type', () => {
+    const cb = vi.fn();
+    renderHook(() => useWsMessage('goals:change', cb));
+    fakeSocket!.fire('message', { data: JSON.stringify({ type: 'tasks:change' }) });
+    fakeSocket!.fire('message', { data: JSON.stringify({ type: 'goals:change', goal: { id: 'g1' } }) });
+    expect(cb).toHaveBeenCalledTimes(1);
+    expect(cb).toHaveBeenCalledWith(expect.objectContaining({ type: 'goals:change' }));
+  });
+
+  it('filters by multiple types', () => {
+    const cb = vi.fn();
+    renderHook(() => useWsMessage(['tasks:change', 'goals:change'], cb));
+    fakeSocket!.fire('message', { data: JSON.stringify({ type: 'activity:new' }) });
+    fakeSocket!.fire('message', { data: JSON.stringify({ type: 'tasks:change' }) });
+    fakeSocket!.fire('message', { data: JSON.stringify({ type: 'goals:change' }) });
+    expect(cb).toHaveBeenCalledTimes(2);
+  });
+
+  it('ignores malformed JSON', () => {
+    const cb = vi.fn();
+    renderHook(() => useWsMessages(cb));
+    fakeSocket!.fire('message', { data: 'not-json{' });
+    expect(cb).not.toHaveBeenCalled();
+  });
+});

package/bizar-dash/src/web/v8/__tests__/views.test.tsx

@@ -0,0 +1,182 @@
+import { describe, expect, it, beforeEach, vi, afterEach } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import { ThemeProvider } from '../ui/theme/ThemeProvider.js';
+import { DensityProvider } from '../ui/theme/DensityProvider.js';
+import { OverviewView } from '../views/Overview/OverviewView.js';
+import { TasksView } from '../views/Tasks/TasksView.js';
+import { GoalsView } from '../views/Goals/GoalsView.js';
+import { AgentsView } from '../views/Agents/AgentsView.js';
+import { ActivityView } from '../views/Activity/ActivityView.js';
+import { MemoryView } from '../views/Memory/MemoryView.js';
+import { LibrariesView } from '../views/Libraries/LibrariesView.js';
+import { SettingsView } from '../views/Settings/SettingsView.js';
+
+/**
+ * Views test (S10) — every view pulls live data from the backend now.
+ * We mock `fetch` so jsdom doesn't try to hit a real server. Each test
+ * asserts: (1) the view renders its title/header, (2) the rendered
+ * surface reflects whatever the mocked endpoint returned.
+ */
+
+function Providers({ children }: { children: React.ReactNode }): JSX.Element {
+  return (
+    <ThemeProvider>
+      <DensityProvider>{children}</DensityProvider>
+    </ThemeProvider>
+  );
+}
+
+interface MockRoute {
+  url: string;
+  body: unknown;
+}
+
+let routes: MockRoute[] = [];
+
+function mockFetch(routesIn: MockRoute[]): void {
+  routes = routesIn;
+  globalThis.fetch = vi.fn(async (input: RequestInfo | URL) => {
+    const url = typeof input === 'string' ? input : input.toString();
+    const match = routes.find((r) => url.startsWith(r.url));
+    if (!match) {
+      return new Response(JSON.stringify({ error: 'not-mocked', url }), { status: 404 });
+    }
+    return new Response(JSON.stringify(match.body), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as typeof fetch;
+}
+
+beforeEach(() => {
+  // Reasonable default — most tests only care about one endpoint.
+  mockFetch([]);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('OverviewView', () => {
+  it('renders the four stat tiles plus activity + needs-attention cards', async () => {
+    mockFetch([
+      { url: '/api/snapshot', body: { overview: { tasks: { active: 2, queued: 1, done: 0, blocked: 0 }, goals: { atRisk: 1, total: 3, done: 1 }, agents: { running: 2, total: 4, idle: 1, error: 0 }, tokens: { last24h: 1_500_000 }, needsAttention: [{ label: 'CI', value: 'failed' }] } } },
+      { url: '/api/activity', body: { events: [] } },
+    ]);
+    render(<Providers><OverviewView /></Providers>);
+    await waitFor(() => {
+      expect(screen.getByText(/Active tasks/i)).toBeInTheDocument();
+    });
+    expect(screen.getByText(/Goals at risk/i)).toBeInTheDocument();
+    expect(screen.getByText(/Agents running/i)).toBeInTheDocument();
+    expect(screen.getByText(/Tokens \(24h\)/i)).toBeInTheDocument();
+    expect(screen.getByText(/Recent activity/i)).toBeInTheDocument();
+    expect(screen.getByText(/Needs attention/i)).toBeInTheDocument();
+  });
+});
+
+describe('TasksView', () => {
+  it('renders kanban column titles for a non-empty task list', async () => {
+    mockFetch([
+      { url: '/api/tasks', body: { tasks: [{ id: 't1', title: 'Ship v8 dashboard', status: 'doing', priority: 'high' }] } },
+    ]);
+    render(<Providers><TasksView /></Providers>);
+    await waitFor(() => {
+      expect(screen.getByText(/Backlog/i)).toBeInTheDocument();
+    });
+    expect(screen.getByText(/In progress/i)).toBeInTheDocument();
+    expect(screen.getByText(/In review/i)).toBeInTheDocument();
+    expect(screen.getByText(/Done/i)).toBeInTheDocument();
+    expect(screen.getByText(/Archived/i)).toBeInTheDocument();
+    expect(screen.getByText(/Ship v8 dashboard/i)).toBeInTheDocument();
+  });
+});
+
+describe('GoalsView', () => {
+  it('renders goal titles pulled from /api/goals', async () => {
+    mockFetch([
+      { url: '/api/goals', body: { goals: [
+        { id: 'g1', title: 'Ship v8 dashboard', status: 'active', progress: 0.5, keyResults: [{ id: 'kr1', title: 'Cut S9 polish in half', done: false }] },
+        { id: 'g2', title: 'Adopt OKLch tokens', status: 'on-track', progress: 0.8, keyResults: [] },
+      ] } },
+    ]);
+    render(<Providers><GoalsView /></Providers>);
+    await waitFor(() => {
+      expect(screen.getByText(/Ship v8 dashboard/i)).toBeInTheDocument();
+    });
+    expect(screen.getByText(/Adopt OKLch tokens/i)).toBeInTheDocument();
+  });
+});
+
+describe('AgentsView', () => {
+  it('renders Bizar + CC agents with the source filter chip', async () => {
+    mockFetch([
+      { url: '/api/agents', body: { agents: [{ name: 'atlas', role: 'coder', status: 'busy' }] } },
+      { url: '/api/cc-agents', body: { agents: [{ id: 's1', sessionId: 's1', name: 'CC worker', kind: 'background', status: 'idle' }] } },
+    ]);
+    render(<Providers><AgentsView /></Providers>);
+    await waitFor(() => {
+      expect(screen.getByText('atlas')).toBeInTheDocument();
+    });
+    expect(screen.getByText('CC worker')).toBeInTheDocument();
+    expect(screen.getByText(/^All$/)).toBeInTheDocument();
+    expect(screen.getByText(/^Bizar$/)).toBeInTheDocument();
+    expect(screen.getByText(/^Claude Code$/)).toBeInTheDocument();
+  });
+});
+
+describe('ActivityView', () => {
+  it('renders the heading even when no events', async () => {
+    mockFetch([{ url: '/api/activity', body: { events: [] } }]);
+    render(<Providers><ActivityView /></Providers>);
+    await waitFor(() => {
+      expect(screen.getByRole('heading', { level: 1, name: /activity/i })).toBeInTheDocument();
+    });
+  });
+});
+
+describe('MemoryView', () => {
+  it('renders scope filter chips and an empty state when no entries', async () => {
+    mockFetch([{ url: '/api/memory', body: { entries: [] } }]);
+    render(<Providers><MemoryView /></Providers>);
+    await waitFor(() => {
+      expect(screen.getByText(/^All$/)).toBeInTheDocument();
+    });
+    expect(screen.getByText(/^Project$/)).toBeInTheDocument();
+    expect(screen.getByText(/^Global$/)).toBeInTheDocument();
+  });
+});
+
+describe('LibrariesView (Skills)', () => {
+  it('renders items fetched from /api/skills', async () => {
+    mockFetch([
+      { url: '/api/skills', body: { skills: [
+        { id: 'frigg', name: 'Frigg', slug: 'frigg', status: 'enabled', description: 'Read-only codebase Q&A.' },
+        { id: 'mimir', name: 'Mimir', slug: 'mimir', status: 'enabled', description: 'Deep codebase research.' },
+      ] } },
+    ]);
+    const { container } = render(<Providers><LibrariesView kind="skills" /></Providers>);
+    await waitFor(() => {
+      expect(container.textContent).toContain('Frigg');
+    });
+    expect(container.textContent).toContain('Read-only codebase Q&A.');
+  });
+});
+
+describe('SettingsView', () => {
+  it('renders the 16 settings sections and shows the active nav', () => {
+    render(<Providers><SettingsView /></Providers>);
+    expect(screen.getByRole('heading', { level: 2, name: /^General$/i })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 2, name: /^Theme$/i })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 2, name: /^Density$/i })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 2, name: /^Privacy$/i })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 2, name: /^Advanced$/i })).toBeInTheDocument();
+  });
+
+  it('marks the General nav entry as the active section', () => {
+    render(<Providers><SettingsView /></Providers>);
+    const navButtons = screen.getAllByRole('button');
+    const generalBtn = navButtons.find((b) => b.textContent === 'General');
+    expect(generalBtn?.getAttribute('aria-current')).toBe('true');
+  });
+});

package/bizar-dash/src/web/v8/data/fetcher.ts

@@ -0,0 +1,59 @@
+/**
+ * v8/data/fetcher.ts — tiny fetch wrapper for the v8 dashboard.
+ *
+ * Thin layer over `fetch` with AbortController support. The dashboard
+ * sits behind the same origin as the API (vite dev proxies /api → :PORT,
+ * prod serves from the same host), so the URL is always relative.
+ *
+ * `useFetch` is React-side; `fetchJson` is the vanilla helper that the
+ * hook uses. Both go through here so we have one place to add
+ * auth headers, retry, etc.
+ */
+
+export class FetchError extends Error {
+  status: number;
+  body: unknown;
+  constructor(status: number, message: string, body: unknown) {
+    super(message);
+    this.name = 'FetchError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export interface FetchJsonOptions {
+  signal?: AbortSignal;
+  method?: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  /** Override the base URL. Default = '' (same-origin). */
+  base?: string;
+}
+
+export async function fetchJson<T>(url: string, opts: FetchJsonOptions = {}): Promise<T> {
+  const init: RequestInit = {
+    method: opts.method || 'GET',
+    headers: {
+      Accept: 'application/json',
+      ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
+      ...(opts.headers || {}),
+    },
+    signal: opts.signal,
+  };
+  if (opts.body !== undefined) init.body = JSON.stringify(opts.body);
+  const fullUrl = (opts.base || '') + url;
+  const res = await fetch(fullUrl, init);
+  const text = await res.text();
+  let parsed: unknown = null;
+  if (text) {
+    try { parsed = JSON.parse(text); } catch { parsed = text; }
+  }
+  if (!res.ok) {
+    const message =
+      (parsed && typeof parsed === 'object' && 'message' in parsed && typeof (parsed as { message: unknown }).message === 'string')
+        ? (parsed as { message: string }).message
+        : `HTTP ${res.status}`;
+    throw new FetchError(res.status, message, parsed);
+  }
+  return parsed as T;
+}

package/bizar-dash/src/web/v8/data/types.ts

@@ -0,0 +1,154 @@
+/**
+ * v8/data/types.ts — Wire types for the dashboard's REST + WS surface.
+ *
+ * Single source of truth for the shapes that flow between the
+ * `bizar-dash` backend and the v8 views. Each interface corresponds to
+ * a route in `src/server/routes/*.mjs`. Keep them narrow — optional
+ * fields stay optional; the backend may emit more keys than the
+ * dashboard needs and that's fine (we ignore them).
+ */
+
+/** `GET /api/snapshot` — top-level dashboard counts. */
+export interface Snapshot {
+  overview: {
+    tasks?: { active?: number; queued?: number; done?: number; blocked?: number };
+    agents?: { running?: number; idle?: number; error?: number; total?: number };
+    goals?: { total?: number; atRisk?: number; done?: number };
+    tokens?: { last24h?: number; trend?: 'up' | 'down' | 'flat' };
+    needsAttention?: Array<{ label: string; value: string; hint?: string }>;
+    recentActivity?: Array<ActivityEvent>;
+  };
+  agents: BizarAgent[];
+  projects: Array<{ id: string; cwd?: string; name?: string }>;
+  activeProject?: { id: string; cwd?: string; name?: string } | null;
+}
+
+/** `GET /api/agents` — Bizar agent roster (frontmatter + runtime status). */
+export interface BizarAgent {
+  name: string;
+  description?: string;
+  model?: string;
+  mode?: string;
+  color?: string;
+  tools?: string[];
+  tags?: string[];
+  category?: string;
+  status?: 'idle' | 'working' | 'error' | 'stuck';
+  currentTaskId?: string | null;
+  currentTaskStartedAt?: number;
+  lastSeen?: number;
+  heartbeat?: number;
+  lastError?: { ts: number; message: string } | null;
+  lastTask?: { id: string; finishedAt: number; status: string } | null;
+  successRate?: number;
+  tasksTotal?: number;
+  tasksSucceeded?: number;
+  tasksFailed?: number;
+  isStuck?: boolean;
+  level?: number;
+  parent?: string | null;
+  role?: string;
+}
+
+/** `GET /api/cc-agents` — Claude Code background agent roster. */
+export interface CCAgent {
+  id?: string;
+  pid?: number;
+  cwd?: string;
+  kind?: 'background' | 'interactive';
+  startedAt?: number;
+  sessionId?: string;
+  name?: string;
+  status?: string;
+  state?: string;
+  lastMessageAt?: number;
+  messageCount?: number;
+  lastMessageSnippet?: string;
+}
+
+/** `GET /api/goals` — long-horizon goals parsed from `.bizar/PROGRESS.md`. */
+export interface Goal {
+  id: string;
+  title: string;
+  status: 'on-track' | 'at-risk' | 'off-track' | 'done' | 'blocked' | 'active';
+  description?: string;
+  progress: number;
+  keyResults: Array<{
+    id: string;
+    title: string;
+    done: boolean;
+    assignee?: string;
+  }>;
+  owner?: string;
+  due?: string;
+  section?: string;
+}
+
+/** `GET /api/tasks` — kanban tasks. */
+export interface Task {
+  id: string;
+  title: string;
+  status?: 'queued' | 'doing' | 'done' | 'blocked' | 'archived';
+  priority?: 'low' | 'medium' | 'high' | 'urgent';
+  description?: string;
+  branch?: string;
+  due?: string;
+  comments?: number;
+  attachments?: number;
+  assignee?: string;
+  metadata?: Record<string, unknown>;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+/** `GET /api/memory` — memo entries. */
+export interface MemoryEntry {
+  id: string;
+  content: string;
+  tags?: string[];
+  scope?: 'project' | 'global';
+  updatedAt?: string;
+  /** Optional references the renderer surfaces as chips. */
+  refs?: Array<{ kind: string; value: string }>;
+}
+
+/** `GET /api/skills`, `/api/mcps`, `/api/hooks` — library items. */
+export interface LibraryItem {
+  id: string;
+  name: string;
+  slug?: string;
+  status?: 'enabled' | 'disabled' | 'error';
+  description?: string;
+  meta?: string;
+  source?: string;
+  path?: string;
+  version?: string;
+  scope?: 'project' | 'global' | 'shipped' | 'user';
+  badges?: string[];
+}
+
+/** Activity event from `/api/activity` (paged) or WS. */
+export interface ActivityEvent {
+  id?: string;
+  kind?: string;
+  title?: string;
+  description?: string;
+  meta?: string;
+  ts?: number;
+  tone?: 'info' | 'success' | 'warning' | 'danger';
+  agent?: string;
+  iconKey?: string;
+  slug?: string;
+}
+
+/** A single WebSocket message from `/ws`. */
+export type WsMessage =
+  | { type: 'tasks:change'; task?: Task }
+  | { type: 'agents:change'; source?: string; digest?: string }
+  | { type: 'agent:status'; agent?: BizarAgent }
+  | { type: 'goals:change'; goal?: Goal }
+  | { type: 'background:change'; id?: string; status?: string }
+  | { type: 'background:syncError'; taskId?: string; instanceId?: string; fails?: number }
+  | { type: 'artifact:new'; artifact?: { id?: string; title?: string } }
+  | { type: 'activity:new'; event?: ActivityEvent }
+  | { type: string; [key: string]: unknown };