coaia-visualizer 1.6.2 → 1.6.3

package/rispecs/ui-component-library.spec.md

@@ -1,258 +0,0 @@
-# UI Component Library
-## RISE Specification for Shared UI Primitives, Theming, and Statistics Display
-
-**Component Purpose**: Provide consistent, accessible, and themed UI primitives across the entire visualizer — built on Radix UI with shadcn patterns, supporting dark/light themes, and including statistical overview components.
-
-**Source Files**: `components/ui/*.tsx`, `components/theme-provider.tsx`, `components/theme-toggle.tsx`, `components/data-stats.tsx`, `components/live-indicator.tsx`, `components/file-upload.tsx`, `lib/utils.ts`
-
----
-
-## 🎯 What This Component Enables Users to Create
-
-- A consistent visual language across all visualizer views
-- Dark/light theme support with system preference detection
-- Accessible UI interactions via Radix UI primitives
-- At-a-glance data statistics for quick structural assessment
-- Live polling status awareness
-- Drag-and-drop file upload experience
-
----
-
-## 🌊 Structural Tension Dynamics
-
-### Current Reality
-The visualizer needs 12+ distinct UI primitive types (buttons, cards, dialogs, inputs, tabs, etc.) plus application-specific components (stats, live indicator, file upload, theme toggle). Without a unified component library, each feature would implement its own styling, creating inconsistency.
-
-### Desired Result
-A coherent component library where:
-- All primitives follow the same design tokens (colors, spacing, borders)
-- Dark/light themes switch seamlessly without component-level overrides
-- Accessibility is built into the foundation (Radix UI handles ARIA, focus management)
-- Application-specific components (DataStats, LiveIndicator, FileUpload) use the same primitives
-
-### Natural Resolution
-Radix UI provides headless, accessible primitives. shadcn patterns add consistent styling via Tailwind CSS class variants (CVA). The `cn()` utility merges class names safely. `next-themes` handles theme persistence.
-
----
-
-## 📋 Utility: `cn()` (lib/utils.ts)
-
-```typescript
-import { clsx, type ClassValue } from 'clsx'
-import { twMerge } from 'tailwind-merge'
-
-export function cn(...inputs: ClassValue[]): string {
-  return twMerge(clsx(inputs))
-}
-```
-
-Used throughout all components to safely combine Tailwind classes with conflict resolution.
-
----
-
-## 📋 UI Primitives (components/ui/)
-
-### Badge
-- **Variants**: default, secondary, destructive, outline
-- **Usage**: Chart level indicators, relation type labels, universe tags, completion status
-
-### Button
-- **Variants**: default, destructive, outline, secondary, ghost, link
-- **Sizes**: default, sm, lg, icon, icon-sm, icon-lg
-- **Usage**: All interactive triggers — save, edit, cancel, add, delete, navigate
-
-### Card (+ Header, Title, Description, Action, Content, Footer)
-- **Structure**: Container → Header (grid layout) → Content → Footer
-- **Usage**: Chart items, stat cards, narrative beat cards, form containers
-- **Notable**: Container queries for responsive header layout
-
-### Dialog (+ Trigger, Content, Overlay, Header, Footer, Title, Description)
-- **Behavior**: Modal with overlay, close button, fade/zoom animations
-- **Usage**: AddMasterChart form, confirmation dialogs
-
-### Input
-- **Features**: File input styling, focus rings, disabled states
-- **Usage**: Date inputs, text fields
-
-### Label
-- **Features**: Radix UI label with icon support, disabled/readonly states
-- **Usage**: Form field labels
-
-### Textarea
-- **Features**: Min-height 80px, focus rings, auto-resize support
-- **Usage**: Desired outcome editing, current reality observations, action descriptions
-
-### Tabs (+ List, Trigger, Content)
-- **Features**: Pill-styled triggers, active state highlighting
-- **Usage**: Actions/Relations tabs in chart detail, Hierarchy/List view toggle, Upload/Create form toggle
-
-### Calendar
-- **Features**: react-day-picker wrapper with custom styling
-- **Usage**: Due date selection in popovers
-
-### Popover (+ Trigger, Content)
-- **Features**: Radix UI popover with portal, positioned relative to trigger
-- **Usage**: Date pickers, action toolbars
-
-### ScrollArea (+ Scrollbar)
-- **Features**: Custom scrollbar styling, vertical/horizontal support
-- **Usage**: Chart list panel scrolling
-
-### Separator
-- **Features**: Horizontal/vertical, decorative by default
-- **Usage**: Section dividers in chart detail
-
----
-
-## 📋 Theme System
-
-### ThemeProvider (`components/theme-provider.tsx`)
-- Wraps `next-themes` ThemeProvider
-- Default theme: dark
-- Attribute-based switching (`class` attribute on `<html>`)
-- System preference detection
-
-### ThemeToggle (`components/theme-toggle.tsx`)
-- Sun icon (in dark mode) / Moon icon (in light mode)
-- Hydration-safe: renders placeholder before mount to avoid SSR mismatch
-- Uses `useTheme()` hook from next-themes
-
-### Color Tokens
-The visualizer uses `chart-1` through `chart-4` color themes for semantic distinction:
-- **chart-1** (teal): Desired outcomes
-- **chart-2** (amber): Current reality
-- **chart-3**: Narrative beats, accents
-- **chart-4**: Statistics, misc
-
----
-
-## 📋 DataStats Component
-
-### Props
-```typescript
-interface DataStatsProps {
-  data: ParsedData
-}
-```
-
-### Render Structure
-```
-┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
-│ 🎯 12   │ │ ✅ 8/15 │ │ 📄 47   │ │ 🔗 32   │
-│ Charts  │ │ Actions │ │ Entities│ │Relations│
-└─────────┘ └─────────┘ └─────────┘ └─────────┘
-```
-
-**Lucide Icons**: `Target` (Charts), `BarChart3` (Actions), `FileText` (Entities), `Network` (Relations)
-
-**Computed Statistics**:
-1. **Charts**: `data.charts.length`
-2. **Actions**: `{completed}/{total}` — iterates all charts, sums action counts, counts completion status
-3. **Entities**: `data.entities.size`
-4. **Relations**: `data.relations.length`
-5. **Total Beats**: computed across all charts but currently unused in display
-
-Each card shows Lucide icon (color-coded chart-1 through chart-4), value, and label.
-
-> **Note**: Toast notifications use `sonner` (imported as `toast` from `sonner`), not the shadcn `use-toast` hook. Both exist in the codebase but `sonner` is the active integration.
-
----
-
-## 📋 LiveIndicator Component
-
-### Props
-```typescript
-{ isLive: boolean }
-```
-
-### Render
-```
-When isLive=true:  ● LIVE          (green pulse animation)
-When isLive=false: ○ Monitoring    (gray, no animation)
-```
-
-- Animated green pulse dot when live data detected
-- Tailwind pulse + shadow animations
-- No interactivity — pure display
-
-### Integration
-Driven by `useLivePolling` hook which polls `/api/watch` and flashes `isLive=true` for 2 seconds when new data detected.
-
----
-
-## 📋 FileUpload Component
-
-### Props
-```typescript
-interface FileUploadProps {
-  onFileLoad: (content: string, fileName: string) => void
-}
-```
-
-### Render
-```
-┌────────────────────────────────────┐
-│         📁 Upload Icon             │
-│                                    │
-│  Drag & drop your .jsonl file      │
-│  or click to browse                │
-│                                    │
-│  Supports .jsonl and .txt files    │
-└────────────────────────────────────┘
-```
-
-**Behavior**:
-- Hidden `<input type="file" accept=".jsonl,.txt">` triggered by card click
-- Drag-and-drop: `handleDragOver` prevents default, `handleDrop` reads first file
-- `FileReader` API reads file as text
-- Passes content and filename to parent via `onFileLoad`
-
----
-
-## 📋 Technology Stack
-
-| Library | Version | Purpose |
-|:---|:---|:---|
-| Radix UI | Various @radix-ui/* packages | Headless accessible primitives |
-| Tailwind CSS | 4.1.9 | Utility-first styling |
-| class-variance-authority (CVA) | — | Component variant management |
-| clsx | — | Conditional class joining |
-| tailwind-merge | — | Conflict-free class merging |
-| next-themes | — | Dark/light theme provider |
-| react-day-picker | — | Calendar date selection |
-| lucide-react | — | Icon library |
-| sonner | — | Toast notifications |
-| recharts | 2.15.4 | Data visualization charts |
-
----
-
-## ✅ Quality Criteria
-
-✅ **Consistency**
-- All components use `cn()` for class management
-- CVA variants ensure consistent styling across instances
-- Color tokens used semantically (chart-1 for outcomes, chart-2 for reality)
-
-✅ **Accessibility**
-- Radix UI provides ARIA attributes, keyboard navigation, and focus management
-- Labels associate correctly with inputs
-- Dialogs trap focus and handle escape key
-
-✅ **Theme Support**
-- Dark mode is default, light mode available
-- Hydration-safe theme toggle (no flash of wrong theme)
-- All components respect theme context
-
-✅ **Responsive Design**
-- Responsive typography (md: breakpoints)
-- Container queries for card header layout
-- ScrollArea for overflow handling
-
----
-
-## 🔗 Related Components
-
-- [chart-visualization-hierarchy.spec.md](./chart-visualization-hierarchy.spec.md) — uses Card, Badge, ScrollArea, Tabs extensively
-- [chart-editing-workflow.spec.md](./chart-editing-workflow.spec.md) — uses Button, Textarea, Dialog, Calendar, Popover
-- [narrative-beats-display.spec.md](./narrative-beats-display.spec.md) — uses Card, Badge
-- [app.spec.md](./app.spec.md) — full application context for all UI components

package/test-data/test-master.jsonl

@@ -1,11 +0,0 @@
-{"type":"Entity","name":"chart_test_master_chart","entityType":"chart","observations":["Master test chart for MCP integration testing"],"metadata":{"createdAt":"2026-01-16T00:00:00.000Z","dueDate":"2026-02-15"}}
-{"type":"Entity","name":"action_Setup_test_environment","entityType":"action","observations":["Setup test environment"]}
-{"type":"Entity","name":"action_Test_basic_operations","entityType":"action","observations":["Test basic operations"]}
-{"type":"Entity","name":"action_Test_telescope_feature","entityType":"action","observations":["Test telescope feature"]}
-{"type":"Relation","from":"chart_test_master_chart","to":"action_Setup_test_environment","relationType":"hasAction"}
-{"type":"Relation","from":"chart_test_master_chart","to":"action_Test_basic_operations","relationType":"hasAction"}
-{"type":"Relation","from":"chart_test_master_chart","to":"action_Test_telescope_feature","relationType":"hasAction"}
-{"type":"Entity","name":"outcome_Complete_MCP_testing","entityType":"desiredOutcome","observations":["Complete MCP integration testing suite"]}
-{"type":"Relation","from":"chart_test_master_chart","to":"outcome_Complete_MCP_testing","relationType":"hasDesiredOutcome"}
-{"type":"Entity","name":"reality_Initial_state","entityType":"currentReality","observations":["Starting MCP test suite","No charts created yet","Need to validate all MCP tools"]}
-{"type":"Relation","from":"chart_test_master_chart","to":"reality_Initial_state","relationType":"hasCurrentReality"}

package/test-results/.last-run.json

@@ -1,4 +0,0 @@
-{
-  "status": "passed",
-  "failedTests": []
-}

package/test-scripts/README.md

@@ -1,325 +0,0 @@
-# COAIA Visualizer MCP Testing Guide
-
-## Overview
-
-This directory contains a complete Docker-based testing environment for the COAIA Visualizer MCP server. The test suite validates all MCP tools, including the telescope functionality.
-
-## Architecture
-
-```
-┌─────────────────────┐
-│   Test Runner       │
-│  (test-scripts/)    │
-└──────────┬──────────┘
-           │
-           ├─────────────┐
-           │             │
-    ┌──────▼──────┐  ┌──▼──────────────┐
-    │  MCP Server │  │  Next.js App    │
-    │   (stdio)   │  │  (HTTP:4321)    │
-    └─────────────┘  └─────────────────┘
-           │                 │
-           └────────┬────────┘
-                    │
-              ┌─────▼─────┐
-              │   Data    │
-              │ (JSONL)   │
-              └───────────┘
-```
-
-## Quick Start
-
-### 1. Set up environment variables (optional)
-
-```bash
-# For Claude CLI testing
-export ANTHROPIC_API_KEY="your_key_here"
-
-# For Gemini CLI testing
-export GOOGLE_API_KEY="your_key_here"
-```
-
-**Note:** API keys are optional. Tests will use direct HTTP calls if not provided.
-
-### 2. Run all tests
-
-```bash
-chmod +x run-mcp-tests.sh
-./run-mcp-tests.sh
-```
-
-This will:
-- Build Docker images for all services
-- Start the visualizer app and MCP server
-- Run the complete test suite
-- Generate test results
-- Clean up containers
-
-## Test Suite
-
-### Test 01: Basic Operations
-- Creates charts via API
-- Lists all charts
-- Verifies chart creation
-
-### Test 02: Telescope Creation
-- Adds action steps to charts
-- Creates telescoped charts from actions
-- Tests both `add_action_step` (with createAsTelescopedChart flag)
-- Tests `create_telescoped_chart` tool
-- Verifies sub-chart creation
-
-### Test 03: Navigation & Hierarchy
-- Retrieves parent charts
-- Retrieves telescoped child charts
-- Verifies parent-child relationships
-- Tests search functionality
-- Validates navigation metadata
-
-## Test Results
-
-After running tests, check:
-- `test-results/test-01/` - Basic operations results
-- `test-results/test-02/` - Telescope creation results
-- `test-results/test-03/` - Navigation results
-- `test-results/test-summary.txt` - Overall summary
-- `test-results/navigation-summary.txt` - Navigation summary
-
-## Manual Testing
-
-### Start services only
-
-```bash
-docker-compose -f docker-compose.test.yml up -d visualizer-app mcp-server
-```
-
-### Access the app
-
-```bash
-# Web UI
-http://localhost:4321
-
-# API endpoint
-curl http://localhost:4321/api/charts
-```
-
-### Run individual tests
-
-```bash
-docker-compose -f docker-compose.test.yml run --rm test-runner /test-scripts/test-01-basic-operations.sh
-```
-
-### Check logs
-
-```bash
-docker-compose -f docker-compose.test.yml logs visualizer-app
-docker-compose -f docker-compose.test.yml logs mcp-server
-```
-
-### Stop services
-
-```bash
-docker-compose -f docker-compose.test.yml down
-```
-
-## MCP Server Configuration
-
-The MCP server is configured via `mcp-config.json`:
-
-```json
-{
-  "mcpServers": {
-    "coaia-visualizer": {
-      "command": "node",
-      "args": ["/app/dist/index.js"],
-      "env": {
-        "VISUALIZER_API_URL": "http://visualizer-app:4321",
-        "VISUALIZER_API_KEY": "test-api-key"
-      }
-    }
-  }
-}
-```
-
-## Connecting with Claude Desktop
-
-To use the MCP server with Claude Desktop:
-
-1. Copy the built MCP server:
-```bash
-docker cp $(docker-compose -f docker-compose.test.yml ps -q mcp-server):/app/dist ./mcp-dist
-```
-
-2. Update Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-```json
-{
-  "mcpServers": {
-    "coaia-visualizer": {
-      "command": "node",
-      "args": ["<path-to>/mcp-dist/index.js"],
-      "env": {
-        "VISUALIZER_API_URL": "http://localhost:4321",
-        "VISUALIZER_API_KEY": "your-api-key"
-      }
-    }
-  }
-}
-```
-
-3. Restart Claude Desktop
-
-## Available MCP Tools
-
-- `create_chart` - Create new structural tension chart
-- `update_chart` - Update existing chart
-- `delete_chart` - Delete chart
-- `search_charts` - Search charts by query
-- `create_telescoped_chart` - **NEW** Telescope existing action into sub-chart
-- `add_action_step` - Add action (optionally as telescoped chart)
-
-## Troubleshooting
-
-### Services won't start
-```bash
-# Check logs
-docker-compose -f docker-compose.test.yml logs
-
-# Rebuild images
-docker-compose -f docker-compose.test.yml build --no-cache
-```
-
-### Tests fail
-```bash
-# Check individual test output
-cat test-results/test-01/*.json
-cat test-results/test-02/*.json
-cat test-results/test-03/*.json
-```
-
-### API connection issues
-```bash
-# Verify network connectivity
-docker-compose -f docker-compose.test.yml exec test-runner curl -v http://visualizer-app:4321/api/charts
-```
-
-## Development
-
-### Modify tests
-
-Edit files in `test-scripts/`:
-- `run-all-tests.sh` - Main test orchestrator
-- `test-01-basic-operations.sh` - Basic CRUD tests
-- `test-02-telescope-creation.sh` - Telescope feature tests
-- `test-03-navigation.sh` - Navigation and hierarchy tests
-
-### Add test data
-
-Add JSONL files to `test-data/`:
-- `test-master.jsonl` - Sample chart with actions
-
-### Update Docker images
-
-Modify:
-- `Dockerfile.app` - Next.js application
-- `mcp/Dockerfile` - MCP server
-- `Dockerfile.test` - Test runner environment
-
-## CI/CD Integration
-
-This test suite can be integrated into CI/CD pipelines:
-
-```yaml
-# Example GitHub Actions
-- name: Run MCP Tests
-  run: |
-    chmod +x run-mcp-tests.sh
-    ./run-mcp-tests.sh
-  env:
-    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-```
-
----
-
-## Global CLI Testing
-
-### Quick Test
-
-```bash
-# Run the verification script
-./test-scripts/verify-global-cli.sh
-```
-
-### Tests Included
-
-#### 1. Bash Verification Script
-**File:** `test-scripts/verify-global-cli.sh`
-
-**What it tests:**
-- ✅ CLI starts without errors
-- ✅ No file watch limit errors (Turbopack)
-- ✅ Server becomes ready within timeout
-- ✅ HTTP endpoint responds correctly
-- ✅ Turbopack uses correct project directory
-
-**Usage:**
-```bash
-./test-scripts/verify-global-cli.sh
-```
-
-#### 2. Playwright End-to-End Tests
-**File:** `test-scripts/test-global-cli.spec.ts`
-
-**What it tests:**
-- ✅ CLI launches without file watch errors
-- ✅ Server starts and responds to HTTP requests
-- ✅ UI loads with correct content
-- ✅ Sample chart data loads correctly
-- ✅ Different port configurations work
-
-**Usage:**
-```bash
-npm run test:global-cli
-```
-
-### Expected Output
-
-#### Successful Test
-```
-🧪 Testing globally installed coaia-visualizer CLI
-📁 Sample file: /a/src/coaia-visualizer/samples/tradingchart.jsonl
-🌐 Port: 3099
-
-⏳ Waiting for server to start (PID: 123456)...
-✅ Server started successfully
-🔍 Testing HTTP response...
-✅ Server responding correctly
-🔍 Checking for file watch errors...
-✅ No file watch errors detected
-🔍 Verifying Turbopack project directory...
-✅ Turbopack using correct project directory
-
-✅ All tests passed! CLI works correctly without file watch errors.
-```
-
-### Testing After CLI Changes
-
-After making changes to the CLI, always:
-
-1. **Rebuild the CLI:**
-   ```bash
-   npm run build:cli
-   ```
-
-2. **Reinstall globally:**
-   ```bash
-   npm install -g .
-   ```
-
-3. **Run verification:**
-   ```bash
-   ./test-scripts/verify-global-cli.sh
-   ```
-
-### Related Documentation
-
-- [CLI_FILE_WATCHING_FIX.md](../CLI_FILE_WATCHING_FIX.md) - Complete fix documentation