# Repository Guidelines

## Project Structure & Module Organization
- `src/`: application code.
  - `components/`: UI components (e.g., `Flashcard/`, `tones/`, `ui/`).
  - `actions/`: server actions (data fetching/mutations).
  - `lib/`: shared types, helpers, config.
- `public/`: static assets served as-is.
- `dist/`: build output (generated).
- `waku.config.ts`: Waku app configuration.
- `bulkdata/`: project data assets.

Use absolute imports with `@/` (configured via tsconfig paths).

## Build, Test, and Development Commands
- Setup: `bun install` — install dependencies.
- Dev: `bunx --bun waku dev` — start the dev server with hot reload.
- Build: `bunx --bun waku build` — produce production build in `dist/`.
- Start: `bunx --bun waku start` — run the production server.

Example: `BUN_INSTALL_CACHE=1 bun install && bunx --bun waku dev`

## Coding Style & Naming Conventions
- Language: TypeScript + React 19, Tailwind CSS 4.
- Components: `.tsx`, PascalCase filenames (e.g., `ToneSelectorClient.tsx`).
- Utilities/types: camelCase files in `lib/`.
- Client components must begin with `"use client"` when using hooks/browser APIs.
- Prefer functional components and hooks; keep side-effects in `useEffect`.
- Follow existing Tailwind class patterns; co-locate small helpers with components.

## Testing Guidelines
- No formal test suite is enforced yet. If adding tests:
  - Place unit tests next to source (`Component.test.tsx`) or under `src/__tests__/`.
  - Use Bun’s test runner (`bun test`) or Vitest if introduced.
  - Keep tests fast and focused; mock network/IO.

## Commit & Pull Request Guidelines
- Commit messages in history are informal; prefer concise, imperative subject lines.
- Recommended: Conventional Commits (e.g., `feat: add tone keyboard nav`).
- PRs should include:
  - What/why summary and screenshots or clips for UI changes.
  - Linked issues or TODO references.
  - Scope-limited diffs and notes on breaking changes or migrations.

## Security & Configuration Tips
- Avoid committing secrets; prefer environment variables (configure via hosting env).
- Validate inputs in server actions under `src/actions/`.
- Keep client-only code behind `"use client"`; avoid leaking server internals to the browser.

## Architecture Notes
- App is a Waku + Bun React app. Pages and interactive views live under `src/components/**`. UI patterns like 3D flip (see `components/Flashcard/`) are shared across features (e.g., `tones/`). Reuse existing utilities and styles for consistency.