aethera/frontend/AGENTS.md

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

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)