# Frontend Agent Instructions

## Stack

- **Bun** (bundler + package manager — no npm)
- **TypeScript** (strict mode, ES2020 target)
- **Alpine.js** (reactivity, bundled via `main.ts` — not CDN)
- **Tailwind CSS 4** (no config file, just `styles.css` with `@import`)
- **marked + marked-highlight + highlight.js** (Markdown rendering)

## Commands

```bash
bun run build   # Production build → public/dist/
bun run dev     # Watch mode (JS + CSS)
bun run lint    # ESLint
```

## Architecture

### Directory Layout

```
src/
  main.ts                # Entry point — imports components, starts Alpine
  client.ts              # All API calls (fetch-based, centralized)
  types/index.ts         # Shared TypeScript interfaces
  utils.ts               # Shared utility functions
  theme.ts               # Theme toggle logic
  components/
    chatManager.ts       # Chat UI — message list, streaming, Markdown
    imageManager.ts      # Image generation/gallery UI
    settingsManager.ts   # Settings form UI
    themeManager.ts      # Theme Alpine component
    navigationManager.ts # Page navigation Alpine component
public/
  index.html             # SPA shell
  pages/
    chats.html           # Chat page template
    images.html          # Images page template
    settings.html        # Settings page template
styles.css               # Tailwind entry point
```

### Key Patterns

- **Alpine.js components**: each `*Manager.ts` registers an `Alpine.data(...)` component. State lives in Alpine's reactive scope + localStorage for persistence.
- **API client**: all backend calls go through `src/client.ts`. Streaming uses NDJSON via `ReadableStream` reader.
- **Build pipeline**: Bun bundles `src/main.ts` → `public/dist/main.js`; Tailwind CLI compiles `styles.css` → `public/dist/styles.css`. Output is copied to `backend/web/static/` by the root `Makefile`.
- **No SPA router**: navigation is handled by Alpine component visibility toggling.

## Non-Negotiables

- ❌ No `any` type — use `unknown` and narrow
- ❌ No `as` type assertions
- ❌ No `@ts-ignore` or `@ts-expect-error`
- ❌ Fix all TypeScript and ESLint errors — don't ignore them
- ❌ No Alpine.js via CDN (it's bundled)
- ❌ Don't commit `public/dist/`

## Code Style

- 2 spaces, single quotes, semicolons required
- camelCase for variables/functions
- PascalCase for types/interfaces
- UPPER_SNAKE_CASE for constants
- Explicit error handling with try/catch
- User-friendly error messages in UI (not just console.log)