# Requirements

## 1. Product Overview

MarketPulse is a browser-based stock dashboard implemented as a single HTML file (`dash.html`) with embedded JavaScript and CSS dependencies.

## 2. Functional Requirements

### 2.1 Market Data Display

- Display market status (open/closed).
- Display major indices (DJI, IXIC, SPX, VIX), with per-index visibility toggles.
- Display gainers and losers list from a configured ticker pool.
- Display up to 3 independent watchlist cards.

### 2.2 Watchlist Management

- Maintain named watchlists with ticker arrays.
- Support create, delete, add ticker, remove ticker operations.
- Provide `None` option for each dashboard watchlist selector.
- Persist selected watchlist per card across reloads.

### 2.3 Preferences & Persistence

- Persist user settings (theme, display toggles, watchlist selections, interval, debug mode).
- Persist API key locally.
- Support storage fallback behavior under browser storage restrictions.

### 2.4 API Features

- Use Finnhub API for quotes and market status.
- API test view accepts user-provided symbol input (not hardcoded).
- Handle invalid key and unavailable quote responses gracefully.

### 2.5 Debugging & Diagnostics

- Debug console supports detailed timestamped logs.
- Logs identify which watchlist/card is being fetched and result status.
- Show partial success/failure status after refresh.
- Include built-in self-test controls.

## 3. Non-Functional Requirements

### 3.1 Usability

- Responsive UI for desktop and tablet/mobile breakpoints.
- Clear status indicators and error messages.

### 3.2 Reliability

- Defensive checks for missing DOM nodes.
- Defensive checks for undefined global state.
- Avoid hardcoded behavior where user input exists.

### 3.3 Performance

- Avoid duplicate/parallel conflicting refreshes.
- Keep watchlist quote requests bounded (max symbols per list).

### 3.4 Maintainability

- Keep docs synchronized with behavior.
- Keep logs descriptive and actionable.
- Keep preference keys versioned if schema evolves.

## 4. External Dependencies

- Browser with JavaScript enabled.
- Internet access for Finnhub API.
- Valid Finnhub API key.
- Bootstrap/Bootswatch CDN availability.