Demo — Ios Architecture

What Exists Today

iOS App — 5 Tabs

⚡

Approvals

SafeBot approval list + detail

ACTIVE

📋

Tasks

Segmented: Tasks / Inbox / Ideas

ACTIVE

💬

Chat

Dual-mode: Converge + Terminal Mirror

ACTIVE

📊

Timeline

Event timeline with filters

ACTIVE

⚙️

Settings

Server, appearance, DND

ACTIVE

Gap: No Web View

No WKWebView, no SFSafariViewController. CUI pages exist on port 3020 but the app can't display them.

Connection Architecture

Chat Path (working)

iPhone

→

Tailscale VPN

→

Dashboard :3020

→

v2 Chat API

→

Claude subprocess

Terminal Mirror (working)

iPhone

→

Tailscale VPN

→

Dashboard :3020

→

Terminal Proxy

→

GhosttyManager

Chat Island Path (new)

iPhone

→

Tailscale VPN

→

Dashboard :3020

→

CUI Page (WKWebView)

→

Chat Island

→

Claude --resume

Agent has page context + selection + persistent conversation + 74 MCP tools

Phase 1 Hardening (Done)

3s timeout

Down from 10s. Fail fast.

Circuit breaker

3 failures → open, 5s cooldown

Queue depth 20

Up from 5. No premature shedding.

RPC logging

Full visibility + health endpoint

Converge UI Framework — Available Now

Templates

6

landing, dashboard, data-browser, docs, settings, index

Islands

8

force-graph, signals, SSE, tabs, theme, data-table, search, toast, copy, modal

CSS Components

30+

cards, stats, badges, grids, forms, tabs, sidebar, prose, buttons...

Three Navigation Models

How do CUI pages fit into the existing 5-tab iOS app?

Criteria

Option 1

Option 2

Option 3

Build effort

Low

High

Medium

Scalability

Limited

Unlimited

Quick access (Approvals)

Preserved

Lost

Preserved

Integration feel

Bolted on

Native

Disruption risk

Minimal

Full rebuild

Moderate

Future-proof

Walls fast

Grows well

01

New "Pages" Tab

Add a 6th tab. List of CUI pages. Tap → full-screen WKWebView. Chat island works through the web view. Minimal disruption.

02

Full Sidebar Navigation

Replace tab bar entirely. Left sidebar with page tree (like Notion/Obsidian). Swipe to reveal. Everything in one navigation model.

03

Hybrid: Tabs + Workspace Sidebar

Keep bottom tabs for quick-access operational views. Rename "Tasks" → "Workspace" with its own sidebar: page browsing + Tasks/Inbox/Ideas. Best of both.

Pros

Approvals stays one tap away
Workspace tab is the "do stuff" hub
Chat tab can merge later (every page has chat)
Scales well — new pages just appear
Familiar pattern (Slack, Discord)
iPad: full sidebar; iPhone: collapsible drawer

Cons

Workspace tab does a lot — needs careful IA
Two levels of navigation (tab → sidebar → content)
Moderate build complexity

Visual Comparison

Tasks

Tasks Inbox Ideas

VE Phase 1

Extract core engine

Chat Island

5 tasks planned

Theme Builder

OKLCH → CSS

CP Phase 2

Push architecture

⚡Approvals

📋Tasks

💬Chat

📊Timeline

⚙️Settings

Current

System Map

VE Phase 1

● active

Chat Island

● queued

CP Phase 2

● planned

What's blocking VE Phase 1?

Ask about this page...

⚡Approvals

🏠Workspace

💬Chat

📊Timeline

⚙️Settings

Option 3: Hybrid RECOMMENDED

The Chat Island Experience

What it feels like when a page thinks.

Scenario: Managing work from your phone

1

You open the System Map page in the Workspace tab. It loads via WKWebView from the dashboard — full CUI page with live data.

2

You see all working items with status badges. You tap "Verification Engine Phase 1" — it highlights with a selection indicator.

3

You pull up the chat sheet and ask: "What's blocking this?" The agent sees your selection via PAGE_DATA context injection.

4

The agent queries the registry (task_query MCP), finds 4 tasks on hold, and responds with specifics: "Tasks #1945, #1950-1952 are on hold pending the core extraction. #1945 has no blockers — it's ready to start."

5

You say: "Create a task to unblock it and mark #1945 as ready." The agent calls task_create + task_update.

6

The system map updates live — SSE pushes the change, signals update the DOM, a subtle animation plays on the changed items. No reload.

7

Tomorrow you open the same page. The chat remembers (--resume picks up the session). "Last time you unblocked VE Phase 1. #1945 is now in_progress — a builder claimed it."

What Makes This Different

Context-Aware

The agent knows what page you're on, what data is displayed, and what you've selected. Not a generic chatbot — a page-specific assistant.

Persistent Memory

--session-id/--resume gives each page's agent its own conversation history. Come back tomorrow and it remembers.

Full Tools

74 MCP tools. Create tasks, update the registry, search memory, query the knowledge graph. Not limited to reading — the agent can act.

Key Technical Insight

You don't need a persistent process. --resume gives you persistent conversation with crash resilience for free.

User sends message

→

spawn claude -p --resume <id>

→

Full context loaded from disk

→

Response streamed via SSE

→

Process exits

Session state persists as JSONL. If the process crashes, the next message picks up exactly where it left off.

Build Sequence

6 steps. First 3 are the Chat Island spec (already written). Last 3 are new.

1. Chat Persistence

Port --session-id/--resume from v2 chat route to ChatManager. Add sessionId to SubprocessOptions.

src/workspace-api/engine/subprocess.ts, chat-manager.ts

SPEC EXISTS ~1 day

2. Chat Island JS Component

Web-side island that connects to chat API. Message UI, streaming display, selection bridge.

src/converge-ui/client/islands/chat.js, routes/v2/chat-island.ts

SPEC EXISTS ~2-3 days

3. Page Context Injection

PAGE_DATA + DOM selections → assemblePrompt. Agent sees what's on the page and what you tapped.

src/workspace-api/engine/context.ts

SPEC EXISTS ~1 day

4. iOS WKWebView Wrapper

Basic web view component that loads CUI pages. Cookie/auth passthrough. JS bridge for native features.

clients/ios/ — new WebPageView.swift

NEW WORK ~1 day

5. iOS Sidebar Navigation

Page list from dashboard API. Sidebar within Workspace tab. Collapsible on iPhone, persistent on iPad.

clients/ios/ — WorkspaceView.swift, PageListSidebar.swift

NEW WORK ~2-3 days

6. Push Architecture (Phase 2)

Server-side terminal cache + SSE streaming. Eliminates 13 req/sec polling. Live page updates.

src/dashboard/terminal-cache.ts, routes/v2/terminal-stream.ts

SPEC EXISTS ~3-4 days

Dependencies

1 → 2 → 3 Chat Island (server-side)

4 → 5 iOS integration (parallel with 1-3)

6 Push architecture (independent, enhances everything)

What Already Exists

v2 Chat Route

PROVEN

--session-id/--resume pattern working. Reference implementation for Chat Island.

src/dashboard/routes/v2/chat.ts

ClaudeSubprocessManager

PROVEN

Subprocess lifecycle, NDJSON parse, SIGTERM→SIGKILL. Just needs sessionId field.

src/workspace-api/engine/subprocess.ts

CUI Islands

PROVEN

Auto-hydration, MutationObserver, props injection. Chat island is just another island.

src/converge-ui/client/islands.js

SSE Infrastructure

PROVEN

Server-sent events for live updates. Used by workspace platform already.

src/converge-ui/client/sse.js

Chat Island Spec

WRITTEN

5 tasks defined. Chat API, chat island JS, context bridge, selection behavior, task execution mode.

docs/specs/spec-chat-island.md

Component Library Assessment

What this page revealed we have, what's missing, and what should be extracted as reusable components.

What We Used On This Page

📊

Stat Card

Label, big number, delta. Used for metrics.

IN STYLES.CSS

🃏

Card

Header, body, footer. Left-border accent variants.

IN STYLES.CSS

🏷️

Badge

6 color variants. Status indicators.

IN STYLES.CSS

📐

Grid Layouts

grid-2, grid-3, grid-auto. Responsive.

IN STYLES.CSS

📑

Tabs

Horizontal tab bar with active state.

IN STYLES.CSS

📱

Sidebar Layout

240px sidebar + content. Collapses on mobile.

IN STYLES.CSS

New Components Built For This Page

These were written inline. If they appear on 2+ pages, extract to shared styles or islands.

🔀

Flow Diagram

Horizontal node → arrow → node chains. Active, new, emphasis variants.

EXTRACT CANDIDATE

📱

Device Mockup

iPhone frame with notch, status bar, tab bar. CSS only.

EXTRACT CANDIDATE

⏱️

Timeline

Vertical step timeline with dots, ready/future states.

EXTRACT CANDIDATE

⚖️

Score Grid

Decision matrix. Criteria × options with color-coded scores.

EXTRACT CANDIDATE

🎯

Option Card

Numbered comparison cards with expandable pros/cons. Recommended badge.

EXTRACT CANDIDATE

🎬

Scenario Walkthrough

Numbered steps with gradient background. User journey visualization.

EXTRACT CANDIDATE

🌈

Hero Section

Gradient background, title, subtitle, stat cards row.

EXTRACT CANDIDATE

Component Library: Do We Need One?

Not yet — but we're close to the threshold.

The CUI framework already has a de facto component library in styles.css — 30+ utility classes and component patterns. What's missing is the visualization components: flow diagrams, timelines, device mockups, decision matrices.

Rule of three: When a pattern appears on 3+ pages, extract it to styles.css (CSS-only components) or islands/ (interactive components). This page is the first heavy user — build 2 more report pages and the extraction targets will be obvious.

What to extract now (already useful across pages): flow-diagram timeline score-grid. These are CSS-only and work immediately in styles.css.

Extract Now (CSS → styles.css)

• .flow-diagram + .flow-node + .flow-arrow
• .timeline + .timeline-item + .timeline-dot
• .score-grid + .score-cell + .score-header
• .hero (gradient background + stat row)

Extract Later (Islands — need JS)

• device-mockup island — configurable tabs, content
• option-picker island — expandable comparison cards
• scenario island — animated step-through
• chat island — the Chat Island itself

iOS Page Browsing & Chat Island

What Exists Today

iOS App — 5 Tabs

Connection Architecture

Phase 1 Hardening (Done)

Converge UI Framework — Available Now

Three Navigation Models

Visual Comparison

The Chat Island Experience

What Makes This Different

Key Technical Insight

Build Sequence

Dependencies

What Already Exists

Component Library Assessment

What We Used On This Page

New Components Built For This Page

Component Library: Do We Need One?