Awesome Cursor Rules Collection

// React + GraphQL (Apollo Client) .cursorrules

// Prefer functional components with hooks
const preferFunctionalComponents = true;

// GraphQL and Apollo Client best practices
const graphqlBestPractices = [
  "Use Apollo Client for state management and data fetching",
  "Implement query components for data fetching",
  "Utilize mutations for data modifications",
  "Use fragments for reusable query parts",
  "Implement proper error handling and loading states",
];

// Folder structure
const folderStructure = `
src/
  components/
  graphql/
    queries/
    mutations/
    fragments/
  hooks/
  pages/
  utils/
`;

// Additional instructions
const additionalInstructions = `
1. Use Apollo Provider at the root of your app
2. Implement custom hooks for Apollo operations
3. Use TypeScript for type safety with GraphQL operations
4. Utilize Apollo Client's caching capabilities
5. Implement proper error boundaries for GraphQL errors
6. Use Apollo Client DevTools for debugging
7. Follow naming conventions for queries, mutations, and fragments
`;

# ResearchGraph Project Overview

!!!
Very important: Document all work in the .logs folder. For example, these files are already in the .logs folder:
- .logs/PROGRESS.md: Any new features should be documented here, with a short description and date
- .logs/REFACTOR.md: Any refactoring should be documented here, with a short description and date
- .logs/ISSUES.md: When working on any issues, always check if they are listed here already. If they are, add a comment to the issue with the date and your progress. If they are not, add the issue to the list.
!!!

## Project Structure

```
research-planner/
├── app/                      # Next.js app directory
│   ├── api/                  # API routes
│   │   └── autocomplete/     # AI feature endpoints
│   ├── page.tsx             # Main app page
│   └── layout.tsx           # Root layout
├── components/              
│   ├── ui/                  # Shared UI components
│   └── ResearchPlanner/     # Main application components
│       ├── components/      # Feature-specific components
│       │   ├── NodeGraph/   # Graph visualization
│       │   ├── SidePanel/   # Node/Edge editing
│       │   ├── Toolbar/     # Control buttons
│       │   └── shared/      # Shared components
│       ├── context/         # React Context providers
│       ├── hooks/           # Custom React hooks
│       ├── utils/           # Utility functions
│       └── types/           # TypeScript definitions
├── .logs/                   # Development documentation
└── __tests__/              # Integration tests
    └── components/
        └── ResearchPlanner/
            └── NodeGraph.test.tsx  # Main graph tests
```

## Core Components

### 1. ResearchPlanner (components/ResearchPlanner/ResearchPlanner.tsx)
Main orchestrator component that:
- Manages application state through hooks and context
- Handles user interactions and events
- Controls layout and rendering
- Manages feature integration

Key responsibilities:
- Node/Edge state management
- Selection handling
- Graph persistence
- Layout control
- Feature coordination

### 2. NodeGraph (components/ResearchPlanner/components/NodeGraph/)
Graph visualization system:
- Node.tsx: Individual node rendering and interactions
- Edge.tsx: Edge visualization and routing (TODO: implement)
- TimelineGrid.tsx: Timeline visualization
- Node.test.tsx: Co-located node tests

Features:
- Interactive node dragging
- Edge creation/editing
- Multi-select operations
- Timeline integration
- Zoom/pan controls

### 3. SidePanel (components/ResearchPlanner/components/SidePanel/)
Node and edge editing interface:
- SidePanel.tsx: Main component containing node/edge editing
  - Node editing functionality
  - Edge editing functionality
  - MDX integration for rich text
  - Property controls
- SidePanel.test.tsx: Component tests

### 4. Toolbar (components/ResearchPlanner/components/Toolbar/)
Control interface:
- Toolbar.tsx: Main component containing:
  - Node creation controls
  - Edge creation toggle
  - Timeline controls
  - AI feature controls
  - Graph operation buttons
- Toolbar.test.tsx: Component tests

## State Management

### 1. Context Providers (components/ResearchPlanner/context/)
- GraphContext.tsx: Core graph state
  - Nodes and edges
  - Timeline configuration
  - File operations
  - GraphContext.test.tsx: Context tests
- SelectionContext.tsx: Selection state
  - Single/multi selection
  - Start/goal nodes
  - Selection operations

### 2. Custom Hooks (components/ResearchPlanner/hooks/)
Active hooks:
- useNodeOperations.ts: Node manipulation (with tests)
- useEdgeOperations.ts: Edge handling (with tests)
- useGraphPersistence.ts: Storage operations (with tests)
- useLayoutManager.ts: Layout calculations
- useIdGenerator.ts: Unique ID management
- useColorGenerator.ts: Visual styling
- useTextFit.ts: Text sizing utilities

Placeholder hooks (to be implemented):
- useNodeSelection.ts: Node selection management
- useProjectStorage.ts: Project persistence

## Core Features

### 1. Node System
Data Structure:
```typescript
interface GraphNode {
    id: number;
    title: string;
    description: string;
    x: number;
    y: number;
    isObsolete: boolean;
    parentId?: number;
    childNodes?: number[];
    isExpanded?: boolean;
    hullPoints?: Point[];
    hullColor?: { fill: string; stroke: string };
}
```

Operations:
- Creation/deletion
- Position management
- Content editing
- Obsolescence marking
- Parent-child relationships
- Subgraph management

### 2. Edge System
Data Structure:
```typescript
interface Edge {
    id: number;
    source: number;
    target: number;
    title: string;
    description: string;
    isPlanned: boolean;
    isObsolete: boolean;
}
```

Operations:
- Interactive creation
- Direction management
- Content editing
- Status tracking
- Visibility control

### 3. Timeline System
Configuration:
```typescript
interface TimelineConfig {
        isActive: boolean;
        startDate: Date;
    pixelsPerUnit: number;
    scale: 'daily' | 'weekly' | 'monthly';
}
```

Features:
- Date-based grid
- Node snapping
- Scale adaptation
- Visual indicators
- Date management

### 4. Subgraph System
Features:
- Hierarchical nodes
- Expand/collapse
- Hull visualization
- Drag-drop organization
- Multi-level management

## Utility Functions (components/ResearchPlanner/utils/)

### 1. hull.ts
- Convex hull calculations for subgraphs
- Point padding and smoothing
- Visual boundary management

### 2. timeline.ts
- Date-grid calculations
- Snapping logic
- Scale management
- Position mapping

### 3. textFit.ts
- Text scaling calculations
- Responsive text fitting
- Size optimization

### 4. Placeholder Utils (to be implemented)
- storage.ts: Storage utilities
- layout.ts: Layout calculations

## Testing

### 1. Test-Driven Development (TDD)
Core principles:
- Write a simple test that describes the desired behavior
- Run the test and see it fail (Red phase)
- Write the minimum code to make the test pass (Green phase)
- Refactor if needed, keeping tests green (Refactor phase)

Guidelines:
- Keep tests focused on behavior, not implementation
- Start with the simplest possible test case
- Add complexity incrementally
- Avoid over-engineering test infrastructure
- If a test is hard to write, the design might be too complex

Example workflow:
```typescript
// 1. Write a simple test describing the behavior
it('should make node B a child of node A when ctrl-dropped', () => {
    // Arrange: Set up the minimum needed nodes
    // Act: Simulate ctrl-drop
    // Assert: Verify parent-child relationship
});

// 2. Run test, see it fail
// 3. Write minimum code to make it pass
// 4. Refactor if needed
```

### 2. Test Structure
Tests are organized in two ways:
- Integration tests in `__tests__/`
  - Focus on user-facing behavior
  - Test complete features
- Co-located component tests
  - Focus on component-specific behavior
  - Keep close to the implementation

### 3. Testing Strategy
- Start with behavior, not implementation
- Write tests before code
- Keep tests simple and focused
- Test one thing at a time
- Use meaningful test names that describe behavior

### 4. Test Coverage
Key behaviors to test:
- User interactions (clicks, drags, etc.)
- State changes
- Visual feedback
- Error cases

## Development Workflow

### 1. Documentation
All development work is documented in .logs/:
- PROGRESS.md: Feature implementation
- REFACTOR.md: Code improvements
- SUBGRAPH.md: Subgraph feature
- ISSUES.md: Known issues

### 2. Feature Development
1. Document design in .logs
2. Implement core functionality
3. Add tests
4. Update documentation

### 3. Code Style
- TypeScript for type safety
- React hooks for state
- Context for global state
- Tailwind for styling
- Jest for testing

## Performance Considerations

### 1. Rendering Optimization
- Selective re-renders
- Memoization
- Virtual scrolling
- Efficient updates

### 2. State Management
- Atomic updates
- Batch operations
- Context splitting
- State normalization

### 3. Layout Performance
- Efficient calculations
- Cached positions
- Optimized algorithms
- Lazy evaluation

# Frontend Rules
Apply the following rules to the frontend codebase

## Shadcn Rule
1. You must use `npx shadcn@latest add <component-name>` to add new shadcn components. Never use `npx shadcn-ui@latest add <component-name>` because it is deprecated.

## EsLint and Component Import/Export Rules
1. Make sure you fix all the linting errors and warnings and component import and export rules.

## Vite + React + Tailwind CSS + TypeScript Rule

1. Style with Tailwind CSS utility classes for responsive design
2. Do not export pages as default, instead export them as named exports and import them with the page name.
3. Import components using absolute paths. Never use relative paths.
4. Remove all the unused imports, variables, and components.

# Backend Rules
Apply the following rules to the backend codebase

## Module installation rules
- Insall necessary python modules for generated code on your own using poetry instead of pip.
- Especially for EmailStr, install pydantic[email].

## Type expression rules
- Do not use call expressions like constr() for type annotations. Instead, use the type annotation directly.

## Import rules
- Do not use relative imports. Instead, use absolute imports.
- Import necessary python modules for generated code.
- Import db dependencies from app.dependencies.database instead of app.dependencies.db.

## Database rules
- Create a new directory for each database model in backend/app/database directory with __init__.py, model.py and service.py.
- New model should be derived from BaseModel and new service should be derived from BaseService. Never miss table=True at the model class definition.
- After every change in database, update __init__.py file in app/database directory to include all the models except for the base model. Then, execute "make initialMigration" to create the initial migration. After that, execute "make applyMigration" to apply the migration on your own. Before executing these commands, make sure to be in the backend directory.

  You are an expert in TypeScript, React, NextJS, HTML, CSS, and website development.

  Code Style and Structure
  - Write concise, technical TypeScript code with accurate examples.
  - Use functional and declarative programming patterns; avoid classes.
  - Prefer iteration and modularisation over code duplication.
  - Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
  - Structure files: exported component, subcomponents, helpers, static content, types.
  - Follow NextJS's official documentation for setting up and configuring your projects: https://nextjs.org/docs
  - Always use Nextjs App Router, and never the Pages Router.

  Naming Conventions
  - Use lowercase with dashes for directories (e.g., components/auth-wizard).
  - Use camcelCase for files (e.g., components/auth-wizard/authWizard.tsx).
  - Favor named exports for components.

  TypeScript Usage
  - Use TypeScript for all code; prefer interfaces over types.
  - Use functional components with TypeScript interfaces.
  - Use strict mode in TypeScript for better type safety.

  Syntax and Formatting
  - Use the "function" keyword for pure functions.
  - Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
  - Use declarative JSX.
  - Use Prettier for consistent code formatting.

  UI and Styling
  - Use React Aria for base UI components.
  - Implement responsive design with Flexbox for screen size adjustments.
  - Use CSS Modules or Tailwind CSS for component styling.
  - Ensure high accessibility (a11y) standards using ARIA roles and native accessibility props.
  - Leverage framer motion for performant animations and transitions.

  Performance Optimization
  - Minimise the use of useState and useEffect; prefer context and reducers for state management.
  - Implement code splitting and lazy loading for non-critical components with React's Suspense and dynamic imports.
  - Profile and monitor performance using JavaScript and React's built-in tools and debugging features.
  - Avoid unnecessary re-renders by memoising components and using useMemo and useCallback hooks appropriately.

  Navigation
  - Use Nextjs for routing and navigation; follow its best practices.

  State Management
  - Use React Context.
  - For complex state management, consider using Zustand.

  Error Handling and Validation
  - Use Zod for runtime validation and error handling.
  - Implement proper error logging using Sentry or a similar service.
  - Prioritise error handling and edge cases:
    - Handle errors at the beginning of functions.
    - Use early returns for error conditions to avoid deeply nested if statements.
    - Avoid unnecessary else statements; use if-return pattern instead.
    - Implement global error boundaries to catch and handle unexpected errors.

  Testing
  - Write unit and integration tests using Vitest and React Testing Library.
  - Consider snapshot testing for components to ensure UI consistency.

  Key Conventions
  1. Rely on Expo's managed workflow for streamlined development and deployment.
  2. Prioritise Core Web Vitals (Load Time, Jank, and Responsiveness).
  3. Follow React and NextJS's best practices for website development.

You are an expert in TypeScript, Node.js, Next.js App Router, React, Shadcn UI, Radix UI, Tailwind CSS and DrizzleORM.

You can refer to the markdown files in `./cursor-docs` to get more context about the project.
Do not forget to update the project plan in `./cursor-docs/project-plan.md` as you work on the project.

You are also excellent at Cloudflare Workers and other tools like D1 serverless database and KV. You can suggest usage of new tools (changes in wrangler.toml file) to add more primitives like:
- R2: File storage
- KV: Key-value storage
  - Always use the existing KV namespace in `wrangler.toml` don't ever create new ones.
- AI: AI multimodal inference
- others primitives in `wrangler.toml`
- After adding a new primitive to `wrangler.toml`, always run `pnpm run cf-typegen` to generate the new types.

Working with env variables and Cloudflare bindings:
```ts
import { getCloudflareContext } from "@opennextjs/cloudflare";

const { env } = await getCloudflareContext();

const EXAMPLE_ENV_VARIABLE = env.EXAMPLE_ENV_VARIABLE;
const db = env.DB;
```

Authentication:
- The authentication logic is in `src/utils/auth.ts` and `src/utils/kv-session.ts` and is based on Lucia Auth.
- If we want to access the session in a server component, we need to use the `getSessionFromCookie` function in `src/utils/auth.ts`.
- If we want to access the session in a client component, we can get it from `const session = useSessionStore();` in `src/state/session.ts`.

Never generate SQL migration files. Instead after making changes to `./src/db/migrations` you should run `pnpm db:migrate [MIGRATION_NAME]` to generate the migrations.

In the terminal, you are also an expert at suggesting wrangler commands
 - Always use pnpm to install dependencies.

Code Style and Structure
- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid classes.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.
- When using a "container" class, use the "mx-auto" class to center the content.
- Never delete any comments in the code unless they are no longer relevant.
- When a fuction has more than 1 parameter, always pass them as a named object.
- Add `import "server-only"` at the top of the file (ignore this rule for page.tsx files) if it's only intended to be used on the server.
- When you have to add a global type, add it to `custom-env.d.ts` instead of `env.d.ts`, because otherwise it will be overridden by `pnpm run cf-typegen`;

Naming Conventions
- Use lowercase with dashes for directories (e.g., components/auth-wizard).
- Favor named exports for components.

TypeScript Usage
- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use maps instead.
- Use functional components with TypeScript interfaces.

Syntax and Formatting
- Use the "function" keyword for pure functions.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.

UI and Styling
- Use Shadcn UI, Radix, and Tailwind for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.
- Optimize for light and dark mode.

Performance Optimization
- Minimize 'use client', 'useEffect', and 'setState'; favor React Server Components (RSC).
- Wrap client components in Suspense with fallback.
- Use dynamic loading for non-critical components.
- Optimize images: use WebP format, include size data, implement lazy loading.

Key Conventions
- Use 'nuqs' for URL search parameter state management.
- Optimize Web Vitals (LCP, CLS, FID).
- Limit 'use client':
- Favor server components and Next.js SSR.
- Use only for Web API access in small components.
- Avoid for data fetching or state management.

Follow Next.js docs for Data Fetching, Rendering, and Routing.

{
    "projectType": "nextjs",
    "language": "typescript",
    "frameworks": ["react", "nextjs"],
    "libraries": [
        "shadcn-ui",
        "radix-ui",
        "tailwindcss",
        "prisma",
        "zod",
        "vercel-ai-sdk"
    ],
    "database": "postgresql",
    "rules": {
        "general": [
            {
                "description": "Utiliser TypeScript pour toutes les fonctionnalités.",
                "enforce": "typescript-only"
            },
            {
                "description": "Favoriser les composants fonctionnels avec hooks.",
                "enforce": "functional-components-only"
            },
            {
                "description": "Ne jamais utiliser de type 'any'.",
                "enforce": "no-any-type"
            },
            {
                "description": "Respecter les conventions de nommage modernes.",
                "enforce": "modern-naming-conventions"
            }
        ],
        "react": [
            {
                "description": "Favoriser les React Server Components (RSC) lorsque possible.",
                "enforce": "prefer-react-server-components"
            },
            {
                "description": "Minimiser les 'use client' directives.",
                "enforce": "limit-use-client"
            },
            {
                "description": "Utiliser Suspense pour la gestion des opérations asynchrones.",
                "enforce": "use-suspense-for-async"
            },
            {
                "description": "Implémenter des limites d'erreur avec des Error Boundaries.",
                "enforce": "error-boundaries-required"
            },
            {
                "description": "Favoriser les composants fonctionnels avec hooks.",
                "enforce": "functional-components-only"
            },
            {
                "description": "Minimser l'utilisation des useEffect",
                "enforce": "minimize-use-effect"
            }
        ],
        "nextjs": [
            {
                "description": "Optimiser pour les performances et les Web Vitals.",
                "enforce": "optimize-web-vitals"
            },
            {
                "description": "Utiliser les bonnes pratiques pour la gestion des données (fetching, caching).",
                "enforce": "best-practices-data-fetching"
            },
            {
                "description": "Mettre en place une gestion des routes sécurisée.",
                "enforce": "secure-routing"
            },
            {
                "description": "Utiliser Prisma pour toutes les interactions avec la base de données.",
                "enforce": "prisma-database-layer"
            }
        ],
        "ui": [
            {
                "description": "Utiliser Tailwind CSS pour toutes les mises en page et styles.",
                "enforce": "tailwindcss-only"
            },
            {
                "description": "Favoriser l'utilisation des composants Shadcn UI et Radix UI.",
                "enforce": "prefer-shadcn-radix"
            },
            {
                "description": "Suivre les meilleures pratiques en matière d'accessibilité (ARIA, WCAG 2.1).",
                "enforce": "accessibility-compliance"
            },
            {
                "description": "Optimiser les animations et transitions avec Tailwind CSS.",
                "enforce": "tailwindcss-transitions"
            },
            {
                "description": "Favoriser une approche mobile-firest responsive avec Tailwind CSS.",
                "enforce": "mobile-first-responsive"
            }
        ],
        "vercel-ai-sdk": [
            {
                "description": "Utiliser les composants server-side pour les intégrations AI.",
                "enforce": "server-side-ai-integration"
            },
            {
                "description": "Limiter les directives 'use client' dans les composants utilisant le SDK AI.",
                "enforce": "minimize-use-client-sdk"
            },
            {
                "description": "Suivre les exemples du SDK Vercel AI pour les outils et les hooks.",
                "enforce": "vercel-ai-sdk-examples"
            }
        ],
        "performance": [
            {
                "description": "Optimiser les images (formats modernes, lazy loading).",
                "enforce": "image-optimization"
            },
            {
                "description": "Utiliser `next/font` pour optimiser les polices.",
                "enforce": "font-optimization"
            },
            {
                "description": "Configurer le cache pour les routes et les données.",
                "enforce": "cache-configuration"
            },
            {
                "description": "Assurer le suivi et l'optimisation des Core Web Vitals.",
                "enforce": "monitor-core-web-vitals"
            }
        ],
        "typescript": [
            {
                "description": "Suivre les bonnes pratiques de typage strict.",
                "enforce": "strict-typescript"
            },
            {
                "description": "Utiliser des interfaces au lieu des types lorsqu'approprié.",
                "enforce": "prefer-interfaces"
            },
            {
                "description": "Éviter les enums au profit des maps constantes.",
                "enforce": "no-enums"
            },
            {
                "description": "Utiliser l'opérateur `satisfies` pour valider les types.",
                "enforce": "use-satisfies-operator"
            }
        ]
    }
}

# v1notes-frontend development rules

You are an expert in TypeScript, React, Vite, and Tailwind CSS, with a focus on building the v1notes-frontend application.

## Code Style and Structure

- Write concise, technical TypeScript code with accurate examples.
- Use functional and declarative programming patterns; avoid classes.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
- Structure files: exported component, subcomponents, helpers, static content, types.

## Naming Conventions

- Use lowercase with dashes for directories (e.g., components/note-editor).
- Use PascalCase for component files (e.g., NoteEditor.tsx).
- Favor named exports for components.

## TypeScript Usage

- Use TypeScript for all code; prefer interfaces over types.
- Avoid enums; use const objects instead.
- Use functional components with TypeScript interfaces.

## Syntax and Formatting

- Use arrow functions for component definitions and callbacks.
- Avoid unnecessary curly braces in conditionals; use concise syntax for simple statements.
- Use declarative JSX.

## UI and Styling

- Use Tailwind CSS for styling components.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.

## State Management and Routing

- Use React Query for server state management and data fetching.
- Utilize React Router for client-side routing.

## Performance Optimization

- Minimize use of useEffect; favor React Query for data fetching and state management.
- Use React.lazy and Suspense for code splitting and dynamic imports.
- Optimize images: use appropriate formats, include size data, implement lazy loading.

## Key Conventions

- Use React Query hooks (useQuery, useMutation) for data fetching and mutations.
- Implement proper error handling and loading states in components.
- Utilize React Router hooks (useNavigate, useParams) for navigation and route parameter access.

## Component Structure

- Separate concerns: create smaller, reusable components (e.g., NoteList, NoteEditor, CategorySelector).
- Use custom hooks for shared logic (e.g., useNotes, useCategories).

## API Integration

- Create a separate api directory for API-related functions and constants.
- Use axios for HTTP requests, with a configured instance for base URL and headers.

## Authentication

- Implement JWT-based authentication.
- Create an AuthContext and useAuth hook for managing authentication state.

## Forms and Validation

- Use react-hook-form for form management and validation.

## Testing

- Write unit tests for critical components and functions using Vitest.
- Use React Testing Library for component testing.

Follow the Vite documentation for build optimization and environment configuration.

# Chat Genius Project Rules

# Component Structure
- Keep React components in src/pages/chat-genius/components/
- Keep hooks in src/pages/chat-genius/hooks/
- Keep server routes in server/routes/chat-genius/
- Keep types in src/pages/chat-genius/types.ts
- Keep utilities in src/pages/chat-genius/utils.ts

# Naming Conventions
- React components: PascalCase (e.g., MessageList.tsx)
- Hook files: snake_case (e.g., use_usernames.tsx)
- Server files: kebab-case (e.g., chat-genius)
- Type interfaces: PascalCase (e.g., Message, Channel)
- Variables/functions: snake_case (e.g., handle_message_click)
- Store keys: 'chat-genius:feature-name'
- Socket events: snake_case with feature prefix
- Voice file IDs: user_voice_{id}
- Constants: UPPER_SNAKE_CASE

# Socket Events
- Prefix all events with 'chat-genius:'
- Handle presence events: join, leave, idle, activity
- Handle workspace events: update, leave
- Handle message events: create, update, delete
- Handle reaction events: add, remove
- Handle file events: upload, delete
- Handle voice events: generate, play
- Handle avatar events: create, clear

# State Management
- Use store.use() for persistent state
- Use useS/useM/useF/useR hooks from lib
- Keep presence state in PresenceProvider
- Keep username state in UsernameProvider
- Keep workspace state in WorkspaceComponent
- Keep message state in MessageList/Thread
- Keep avatar/voice state in ChatArea

# Feature Integration
- Voice: Use ElevenLabs API through voice.js
- Avatar: Handle through model.js avatar channels
- Files: Upload through file.js with proper headers
- Search: Use vector DB through llm.js
- Messages: Handle threading and reactions
- Presence: Track through socket events
- Workspaces: Manage invites and permissions

# Error Handling
- Handle socket disconnects gracefully
- Validate all API responses
- Handle file upload failures
- Handle voice generation limits
- Handle avatar chat errors
- Handle search query failures
- Handle presence sync issues

# Assistant Behavior
- Always read affected files before making changes
- Never modify code unrelated to the requested change
- Keep existing functionality intact when adding features
- Preserve working socket/store/provider patterns
- Make minimal changes to achieve the goal
- Fix only the specific issue reported
- If unsure about a file's purpose, gather more context first
- When editing files:
  - Use "// ... existing code ..." to preserve unmodified sections
  - Show sufficient context around edits
  - Never rewrite entire files unless explicitly requested
  - Keep working imports and dependencies
  - Maintain existing error handling
  - Preserve type definitions
- When suggesting commands:
  - Explain the purpose clearly
  - Use proper error handling
  - Preserve the working environment
  - Never delete or overwrite critical files

# What Not To Change
❌ Socket event patterns
❌ Store key formats
❌ Provider structure
❌ Hook naming patterns
❌ File organization
❌ Error handling flows
❌ API response formats

# Acceptable Changes
✅ Add new features following patterns
✅ Extend existing components
✅ Add new socket events with prefix
✅ Add new store keys with prefix
✅ Add new hooks following pattern
✅ Add new error handlers
✅ Add new API endpoints

# 프로젝트 개발 가이드라인

## 1. 컴포넌트 가이드라인

### ShadCN Components
- 모든 UI 컴포넌트는 ShadCN을 사용해야 합니다.
- 컴포넌트 사용 전 설치 여부를 확인해야 합니다: '/components/ui' 디렉토리 체크
- 컴포넌트 설치 명령어를 사용해야 합니다: 'npx shadcn@latest add [component—name]'
    - 주의: 'npx shadcn—ui@latest add' 명령어는 deprecated. 반드시 'npx shadcn@latest add'를 사용해야 합니다.

### lcons

- 모든 아이콘은 Lucide React를 사용해야 합니다
- 아이콘 임포트 방법: 'import { IconName } from "lucide—react"'
- 예시: 'import { Search, Menu } from "lucide—react"'

### Component Structure

- 컴포넌트는 '/components' 디렉토리 내에 위치해야 합니다
- UI 컴포넌트는 '/components/ui' 디렉토리에 위치해야 합니다
- 페이지별 컴포넌트는 '/app' 디렉토리 내 해당 라우트에 위치해야 합니다

### Core Practices

- TypeScript types must be strictly defined.
- Follow the user requirements carefully and precisely.
- First, think step-by-step—describe your plan for what to build in pseudocode, written out in great detail.
- Confirm the plan with the user, then write the code!
- Always write correct, up-to-date, bug-free, fully functional, secure, performant, and efficient code.
- Focus on readability over performance.
- Fully implement all requested functionality.
- Leave NO to-dos, placeholders, or missing pieces in the code.
- Ensure the code is complete! Thoroughly verify the final version.
- Include all required imports, and ensure proper naming of key components.
- Be concise. Minimize unnecessary explanations and redundancy.
- If you believe there might not be a correct answer, say so. If you do not know the answer, admit it instead of guessing.
- Always provide concise, precise answers.
- Ensure reusability and modularity in your code to facilitate scalability and future development.
- Components must be designed to be reusable.
- Include comprehensive test cases to validate the functionality, edge cases, and performance of the code.
- Provide concise and clear documentation for the purpose, functionality, and usage of the code, such as comments or README files.
- Implement proper error handling and exception management to make the code robust and user-friendly.
- Maintain collaboration-friendly code by using clear naming conventions, consistent formatting, and a logical structure that a team can easily understand.
- Please answer in Korean.

# UI Text Rules
- All UI text should be lowercase, except for proper nouns (names, brands, etc.)
- Text should be concise and direct
- Remove unnecessary words and verbosity
- Use consistent terminology across components
- Remove explanatory text when the UI is self-explanatory
- Keep error messages short and clear (e.g., "invalid credentials")

# Examples
✅ "sign in" instead of "Sign In" or "Login"
✅ "username" instead of "Enter your username"
✅ "invalid credentials" instead of "The username or password you entered is incorrect"
✅ "need an account?" instead of "Don't have an account? Sign up"

# Component Naming
- Keep React component names in PascalCase (e.g., Login, Button)
- Keep file names in kebab-case (e.g., sign-up.tsx)
- Keep CSS class names in kebab-case

# Spacing
- Use minimal spacing between elements (e.g., space-y-2)
- Keep forms compact (max-width: 320px)
- Use consistent padding (e.g., pt-4 for card content)
- Reduce vertical whitespace in forms
- Keep header height compact (h-12)
- Use small text (text-sm) for secondary information

# Button Rules
- Use small buttons where possible (size="sm")
- Keep button text concise
- Use ghost variant for secondary actions
- Use consistent height for header buttons (h-7) 

# Code Modification Rules
- Only make explicitly requested changes
- No unintended side effects when making changes
- Keep all working functionality intact
- Never modify code that isn't part of the requested change
- Never remove working functionality or code
- Preserve existing code behavior
- Keep working error handling
- Maintain existing security measures
- Preserve working CORS configurations

# File Structure Rules
- Keep existing file organization
- Keep existing file paths and structures
- Maintain working import/export structure
- Preserve working file relationships
- Keep existing file naming conventions
- Maintain directory hierarchy
- Keep existing file names and locations

# Configuration Rules
- Keep working environment setups
- Preserve working build processes
- Maintain deployment configurations
- Keep working cache settings
- Preserve CORS settings
- Keep working auth configurations
- Maintain database connections
- Preserve existing environment variables
- Keep working database schemas and tables
- Preserve working RLS policies
- Keep working edge function configs
- Maintain working realtime subscriptions
- Keep working edge function CORS headers
- Preserve working rate limits
- Maintain working webhook configurations
- Keep working storage bucket settings

# API & Database Rules
- Keep working API endpoints
- Preserve working database triggers
- Maintain working stored procedures
- Keep working database indexes
- Preserve working database constraints
- Keep working database roles

# Authentication Rules
- Keep working auth providers
- Preserve working auth callbacks
- Maintain working auth redirects
- Keep working auth policies
- Preserve working JWT settings

# Version Control Rules
- Keep working lock file entries
- Preserve dependency versions
- Maintain peer dependencies
- Keep working node version settings
- Preserve typescript configurations
- Keep existing gitignore patterns

# Example: What Not To Change
❌ Modifying code beyond requested changes
❌ Changing working configurations
❌ Altering existing security measures
❌ Modifying working error handling
❌ Changing working CORS settings
❌ Altering working auth flows
❌ Modifying working database connections
❌ Removing working build commands
❌ Changing working file paths
❌ Modifying working database schemas
❌ Changing working RLS policies
❌ Altering working stored procedures
❌ Modifying working auth flows
❌ Changing working realtime subscriptions
❌ Modifying working build scripts
❌ Changing working build paths
❌ Altering working CORS headers
❌ Modifying working rate limits
❌ Changing working storage settings

# Example: Acceptable Changes
✅ Making only requested modifications
✅ Adding new functionality without breaking existing code
✅ Extending configurations without breaking working ones
✅ Adding new security measures alongside existing ones
✅ Creating new files without modifying existing ones
✅ Adding new environment variables
✅ Adding new dependencies
✅ Adding new database tables
✅ Creating new stored procedures
✅ Adding new RLS policies
✅ Extending existing schemas
✅ Adding new build scripts
✅ Creating new storage buckets
✅ Adding new rate limits 

# Assistant Behavior Rules
- Only make changes explicitly requested by the user
- Never suggest "improvements" to working code
- Never try to "clean up" or "optimize" working code
- Never remove code just because it seems unused
- Never change formatting of working code
- Never modify indentation unless requested
- Never rewrite working code in a "better" way
- Never add "missing" error handling to working code
- Never add "helpful" comments to working code
- Never change variable/function names to be "clearer"

# Code Block Rules
- Always include file path when suggesting edits
- Use "// ... existing code ..." to mark unchanged sections
- Show enough context around changes for clear location
- Never rewrite entire files unless specifically requested
- Keep all working code markers and comments intact
- Use correct file paths matching project structure
- Use format: ````language:path/to/file
- Include full path from project root
- Match existing directory structure
- Keep consistent path separators

# Example: What Not To Do
❌ "This code could be improved by..."
❌ "I've cleaned up the formatting..."
❌ "I've added better error handling..."
❌ "I've made the variable names clearer..."
❌ "I've optimized this section..."
❌ Using incorrect/incomplete paths
❌ Missing file paths in codeblocks
❌ Using wrong path separators

# Example: Correct Behavior
✅ Only showing requested changes
✅ Keeping existing code markers
✅ Maintaining current formatting
✅ Preserving working code structure
✅ Including clear file paths
✅ Using full paths from root
✅ Matching project structure

# Suggestion Rules
- Suggestions should be clearly marked as optional
- Explain why each suggestion might be helpful
- Show suggestions separately from requested changes
- Never mix suggestions with direct changes
- Always preserve working code in suggestions
- Make suggestions additive, not replacements
- Provide context for each suggestion
- Let user choose which suggestions to implement

# Example: Good Suggestions
✅ "Optional improvement: Could add input validation here..."
✅ "Consider adding error logging to help with debugging..."
✅ "Might want to add a loading state for better UX..."
✅ "Could add type safety by extending the Profile interface..."

# Example: Bad Suggestions
❌ "I've improved the code by..."
❌ "This code should be changed to..."
❌ "The better way to do this is..."
❌ "I fixed the code by..." 

# Edge Function Rules
- Always check existing functions first (e.g., sign-in-with-username)
- Match existing query patterns exactly
- Use parameterized queries always
- Never interpolate values into SQL
- Keep working CORS configurations
- Maintain consistent error handling
- Follow existing security patterns
- Keep function naming consistent
- Verify data exists before use
- Check array bounds
- Deploy after every change (cd back && supabase functions deploy function-name)
- Always specify project ref when deploying (--project-ref <ref>)
- When changing data structure (e.g., array to single), update all references
- Check all usages after changing return types

# Example: What Not To Do
❌ Writing new query patterns without checking existing ones
❌ Using string interpolation in SQL
❌ Changing CORS without testing
❌ Deploying from wrong directory
❌ Breaking existing patterns
❌ Using data without checks
❌ Modifying function without deploying

# Example: Correct Steps
✅ Check sign-in-with-username first
✅ Use parameterized queries
✅ Match existing patterns
✅ Deploy after changes
✅ Test after deployment
✅ Verify security 

You have extensive expertise in Vue 3, Nuxt 3, TypeScript, Node.js, Vue Router, VueUse, Nuxt UI, UnJs ecosystem, and Tailwind CSS. You possess a deep knowledge of best practices and performance optimization techniques across these technologies.

Code Style and Structure
- Write clean, maintainable, and technically accurate TypeScript code.
- Prioritize functional and declarative programming patterns; avoid using classes.
- Emphasize iteration and modularization to follow DRY principles and minimize code duplication.
- Prefer Composition API <script setup lang="ts"> style.
- Use Composables to encapsulate and share reusable client-side logic or state across multiple components in your Nuxt application.

Nuxt 3 Specifics
- Nuxt 3 provides auto imports, so theres no need to manually import 'ref', 'useState', or 'useRouter'.
- For color mode handling, use the built-in '@nuxtjs/color-mode' with the 'useColorMode()' function.
- Take advantage of VueUse functions to enhance reactivity and performance (except for color mode management).
- Use the Server API (within the server/api directory) to handle server-side operations like database interactions, authentication, or processing sensitive data that must remain confidential.
- Authentication should be handled using the nuxt-auth-utils module.
- use useRuntimeConfig to access and manage runtime configuration variables that differ between environments and are needed both on the server and client sides.
- For SEO use useHead and useSeoMeta.
- For images use <NuxtImage> or <NuxtPicture> component and for Icons use Nuxt Icons module.
- use app.config.ts for app theme configuration.

Fetching Data
1. Use useFetch for standard data fetching in components that benefit from SSR, caching, and reactively updating based on URL changes.
2. Use $fetch for client-side requests within event handlers or when SSR optimization is not needed.
3. Use useAsyncData when implementing complex data fetching logic like combining multiple API calls or custom caching and error handling.
4. Set server: false in useFetch or useAsyncData options to fetch data only on the client side, bypassing SSR (if ssr: true).
5. Set lazy: true in useFetch or useAsyncData options to defer non-critical data fetching until after the initial render.

Naming Conventions
- Utilize composables, naming them as use<MyComposable>.
- Use **PascalCase** for component file names (e.g., components/MyComponent.vue).
- Favor named exports for functions to maintain consistency and readability.

TypeScript Usage
- Use TypeScript throughout; prefer interfaces over types for better extendability and merging.
- Avoid enums, opting for maps for improved type safety and flexibility.
- Use functional components with TypeScript interfaces.

UI and Styling
- Use Nuxt UI and Tailwind CSS for components and styling.
- Implement responsive design with Tailwind CSS; use a mobile-first approach.

You are an expert in UI/UX design and front-end development, specializing in creating modern, accessible, and performant web applications.

Create a responsive, fully accessible e-commerce website in Portuguese (pt-br) using React, React Router Vite, TypeScript, Shadcn UI, and Framer Motion.

The e-commerce platform must allow users to list their own items and shop for items from others. The design must include light mode and dark mode themes with smooth transitions between them.
Key Requirements
Visual Design

    Implement a clean, minimal, and modern design with light and dark mode counterparts:
        Light Mode:
            Primary color: Indigo shades (e.g., #4B0082) for branding and key interface elements.
            Secondary color: Muted blues or grays (e.g., #E5E7EB) for subtle UI elements and backgrounds.
            Accent color: Warm tones like amber (#FFC107) or coral (#FF7043) for calls-to-action like "Buy Now".
            Background: Light neutral shades (e.g., #F9FAFB) for a clean, airy look.
            Text: Dark grays (e.g., #111827) for high contrast against light backgrounds.
        Dark Mode:
            Primary color: Indigo tones slightly desaturated (e.g., #3730A3) to reduce brightness.
            Secondary color: Soft blues or dark neutrals (e.g., #1F2937) for secondary elements and backgrounds.
            Accent color: Vibrant warm tones (e.g., #FFB020 or #FF5733) to maintain visibility and energy in dark contexts.
            Background: Dark gray shades (e.g., #111827) to reduce eye strain.
            Text: Light neutrals (e.g., #E5E7EB) for readability against dark backgrounds.

Interaction Design

    Use Framer Motion for smooth transitions between light and dark modes.
    Provide clear visual feedback for actions like toggling modes, adding items, or viewing details.

Accessibility

    Ensure both themes meet WCAG 2.1 AA contrast standards.
    Include semantic HTML, keyboard navigability, and focus states for all interactive elements.

Mobile Responsiveness

    Use mobile-first design principles.
    Ensure components like navigation, product cards, and buttons are touch-friendly with sufficient spacing.

Performance Optimization

    Optimize assets separately for light and dark modes to minimize performance impacts.
    Preload critical resources for both themes to ensure a seamless experience.

Design Patterns and Documentation

    Develop a design system that supports both light and dark modes, with reusable components.
    Document all design decisions, including color codes, typography, and spacing rules for both themes.
    Provide detailed user flows and style guides for developers to extend the system.

First Steps
1. Reusable Components

    Create foundational components for consistency and reusability:
        Button: Configurable for primary, secondary, and disabled states, with hover and focus effects.
        Card: Displays product images, title, price, and action buttons (e.g., "Buy", "Add to Cart").
        Navbar: Responsive navigation with a logo, links, search bar, and light/dark mode toggle.
        Footer: Minimal footer with navigation links and branding.

2. Landing Page

    Use the reusable components to build the homepage:
        Hero Section: Highlight the platform's purpose with a bold call-to-action button (e.g., "Start Selling").
        Featured Products: Grid showcasing a selection of product cards.
        Key Features Section: Highlight the benefits of the platform (e.g., "Sell Easily", "Shop Securely").
        Footer: Include navigation links, branding, and any additional informational links.

3. Responsiveness

    Ensure the design adapts seamlessly across devices and screen sizes.
    Test touch interactions and ensure components have enough spacing for mobile use.

4. Smooth Transitions

    Use Framer Motion for animations like:
        Light/dark mode transitions.
        Hover effects on buttons and cards.
        Page transitions (e.g., navigating to product details).