# askme-ui CLAUDE.md
## UI-Specific Implementation Details
### Angular 20+ Modern Features
- **Standalone Components**: All components use the standalone: true flag
- **Signals**: Reactive state management using Angular signals
- **New Control Flow**: Uses @if and @for instead of *ngIf and *ngFor
- **Computed Signals**: Used for derived state (currentRequest, selectedCount, etc.)
- **Markdown Rendering**: Uses ngx-markdown library for rich text display
- Automatic markdown detection with regex patterns
- Styled to match blueprint theme with custom CSS
### Component Architecture
1. **RequestHandlerComponent** (`components/request-handler/request-handler.component.ts`)
- Main container component
- Manages MCP client connection
- Direct request/response handling without sessions or queues
- Requests notification permissions on init
2. **RequestDisplayComponent** (`components/request-display/request-display.component.ts`)
- Pure presentation component
- Displays request details with relative timestamps
- Shows context in collapsible details element
- **Markdown Support**: Automatically detects and renders markdown-formatted questions using ngx-markdown
- Detects common markdown syntax (headers, bold, italic, code, lists, links, etc.)
- Renders with proper styling consistent with blueprint theme
- Falls back to plain text for non-markdown questions
3. **ResponseInputComponent** (`components/response-input/response-input.component.ts`)
- Form component with tool redirect buttons for switching question formats
- Custom response textarea with character limit (1000)
- Ctrl/Cmd+Enter to submit
- **Completion Status Feature**: Icon buttons for client guidance positioned between "Clear" and "Submit"
- ✅ Done button - tells client to stop asking questions (tooltip: "Submit and I am done with Answering")
- 🔍 Drill Deeper button - encourages follow-up questions (tooltip: "Submit, drill deeper with more single questions")
4. **MultipleChoiceResponseComponent** (`components/multiple-choice-response/multiple-choice-response.component.ts`)
- Handles multiple choice questions with selectable options
- Expandable comment fields for each option
- Selection summary and bulk actions
- **Completion Status Feature**: Icon buttons for client guidance positioned between "Clear" and "Submit"
- ✅ Done button - tells client to stop asking questions (tooltip: "Submit and I am done with Answering")
- 🔍 Drill Deeper button - encourages follow-up questions (tooltip: "Submit, drill deeper with more multiple choice questions")
5. **HypothesisResponseComponent** (`components/hypothesis-response/hypothesis-response.component.ts`)
- Evaluates hypotheses using 7-step agreement scale with emoji icons
- Individual hypothesis comments and "won't answer" options
- Entire challenge "won't answer" option with explanation field
- **Completion Status Feature**: Icon buttons for client guidance positioned between "Clear" and "Submit"
- ✅ Done button - tells client to stop asking questions (tooltip: "Submit and I am done with Answering")
- 🔍 Drill Deeper button - encourages follow-up questions (tooltip: "Submit, drill deeper with more hypothesis challenges")
6. **ChooseNextResponseComponent** (`components/choose-next-response/choose-next-response.component.ts`)
- **NEW**: Workflow decision-making interface for requirements, ideation, specification processes
- Displays options as animated, clickable cards in responsive grid layout
- Each option shows title, description, and optional icon/emoji
- Three response types: Select option, Abort (reject all), Request new ideas
- Markdown support for rich descriptions with blueprint-themed styling
- Consistent bail-out pattern for tool switching
### Service Layer
- **McpClientService**:
- Manages SSE connection via EventSource API
- Reactive state with signals for single request handling
- Auto-reconnection with 5-second delay
- HTTP POST for sending responses (single question, multiple choice, hypothesis challenge, and choose-next)
- **NotificationService**:
- Wrapper around browser Notification API
- Permission management with signal
- Auto-close notifications with timeout
### Testing Specifics
- Mock EventSource with proper constants (CONNECTING, OPEN, CLOSED)
- Mock Notification API as jest.fn() with properties
- Use TestBed.inject() for service instances
- Handle zone.js warnings in tests (normal behavior)
- Text content assertions need .trim() due to Angular formatting
### Routing
- Single route: `/request-handler`
- Default redirect to `/request-handler`
- Lazy loaded components for better performance
### Blueprint Paper Background Theme
The UI features an authentic oldschool blueprint paper background implemented globally:
#### Implementation:
- **Global background**: Applied to `body` element in `styles.scss`
- **Multi-layer grid system**:
- Fine lines (4px/1mm) - subtle detail grid
- Medium lines (20px/5mm) - reference grid
- Major lines (40px/10mm) - measurement grid
- **Classic blueprint colors**: Dark blue background (#0d1929) with light blue grid lines
- **Paper texture**: Subtle radial gradient noise overlay
- **Fixed attachment**: Grid stays in place during scrolling
#### Component Transparency:
- All component backgrounds use `rgba()` with 85-95% opacity
- Semi-transparent overlays with `backdrop-filter: blur()` for modern glass effect
- Blueprint-themed borders using blue accent colors
- Grid is visible behind all content on every page including waiting states
#### Visual Design:
- Maintains excellent text readability on semi-transparent backgrounds
- Professional technical drawing aesthetic
- Grid visible behind question cards, headers, waiting messages, and all UI elements
- Preserves all functionality while adding authentic engineering/blueprint look
### State Management
- All state managed through signals in services
- Components expose service signals directly
- No additional state management library needed
### Browser Compatibility
- EventSource API for SSE (wide support)
- Notification API with permission handling
- Graceful degradation when features unavailable
### SSE Connection
- Connects to `/mcp/browser-events` endpoint (no session ID needed)
- EventSource API cannot send custom headers (browser limitation)
- Connection status shown in top-right corner (green = connected, red = disconnected)
- Automatic reconnection with 5-second delay on connection errors
- Expects initial message `{ type: 'connected' }` to confirm connection
- Single request model - replaces any existing request with new incoming request
### UI/UX Design Patterns
#### Bail-out Button Pattern
All response components follow a consistent bail-out button pattern for tool switching:
**Design Standards:**
- **Position**: Big, prominent buttons at the top of each component (above main content)
- **Styling**: Gradient background (#fff3cd to #ffeaa7), yellow border (#ffc107), with hover effects
- **Size**: Large buttons (min-width: 280px) with emojis and descriptive text
- **Responsive**: Stack vertically on mobile (flex-direction: column)
**Implementation Across Components:**
1. **ResponseInputComponent** (Single Question):
- 📝 Use Multiple Choice Instead
- 🔍 Use Hypothesis Challenge Instead
2. **MultipleChoiceResponseComponent**:
- 🤔 Use Open Question Instead
- 🔍 Use Hypothesis Challenge Instead
3. **HypothesisResponseComponent**:
- 🤔 Use Open Question Instead
- 📝 Use Multiple Choice Instead
**Benefits:**
- Early decision point for users to switch tool types
- Consistent UX across all components
- Prominent visual hierarchy guides user attention
- Mobile-friendly responsive design
**Message Handling:**
- Uses emphatic, direct language with "STOP!", "REFUSES", and "DEMANDS" to ensure LLMs understand the urgency
- Commands immediate action with "IMMEDIATELY reformulate" and "Do NOT continue"
- Tailored to each tool type with specific reformulation instructions
#### Completion Status Pattern (All Tool Types)
- Small circular icon buttons positioned between "Clear" and "Submit" buttons
- ✅ Done button (green) - tells client to stop asking questions
- 🔍 Drill Deeper button (blue) - encourages tool-specific follow-up questions
- CSS class `.btn-icon` with hover effects and proper spacing
- Sends `completionStatus` field in response for server processing
- Tool-specific tooltips explain the drill deeper behavior for each tool type
## Request Lifecycle & State Management
### Timeout and Cancellation Handling
#### Message Type Tracking
The UI now tracks the reason for request clearing to show appropriate user feedback:
```typescript
// In MCP Client Service
private _lastClearReason = signal<'timeout' | 'cancelled' | null>(null);
lastClearReason = this._lastClearReason.asReadonly();
// Set reason before clearing requests
case 'request_timeout': this._lastClearReason.set('timeout');
case 'request_cancelled': this._lastClearReason.set('cancelled');
```
#### UI State Management Pattern
Request clearing detection in RequestHandlerComponent:
```typescript
// Detect request clearing and show appropriate message
if (!activeRequest && this.currentRequest()) {
const clearReason = this.mcpClient.lastClearReason();
if (clearReason === 'timeout') this.showTimeoutMessage();
else if (clearReason === 'cancelled') this.showCancellationMessage();
}
```
#### Sequential Message Display
**IMPORTANT**: User feedback messages show exclusively, then fade to waiting state:
```typescript
// Template structure - nested @if/@else for sequential display
@if (recentTimeout(); as timeout) {
// Show timeout message only
} @else {
@if (recentCancellation(); as cancellation) {
// Show cancellation message only
} @else {
// Show waiting UI only
}
}
```
**Angular Template Limitation**: Cannot use `as` expressions with `@else if` blocks. Must use nested `@if/@else` structure instead.
#### Message Types & Styling
- **Timeout**: Orange banner with ⏰ "Request Timed Out"
- **Cancellation**: Red banner with ❌ "Aborted by Client"
- **Waiting**: Blue banner with connection status
- **Auto-dismiss**: All messages fade after 10 seconds
#### SSE Message Handling
The service handles these server events:
- `request_timeout` → Shows timeout message and clears UI
- `request_cancelled` → Shows cancellation message and clears UI
- `new_request` → Clears previous messages and shows new request
### Testing Considerations
- Mock `lastClearReason` signal when testing request clearing scenarios
- Test sequential message display (timeout → waiting, cancellation → waiting)
- Verify message auto-dismissal after 10 seconds
