# Planning Guide

AeThex Studio is a browser-based cross-platform game development IDE with file management, multi-platform preview, AI assistance, and project templates.

**Experience Qualities**: 
1. **Professional** - Should feel like a complete IDE with file navigation, tabs, and split panels like VS Code
2. **Intelligent** - AI assistance deeply integrated with context awareness and code suggestions
3. **Cross-Platform** - Unified workspace showing Roblox, Web, and Mobile development simultaneously

**Complexity Level**: Complex Application (advanced functionality with multiple views and state management)
This is now a full-featured IDE with file tree navigation, multiple open files, tabbed editor, AI chat panel, console output, multi-platform preview, and project templates - creating a complete game development workspace.

## Essential Features

### File Tree Navigator
- **Functionality**: Left sidebar showing folder/file hierarchy with create, rename, and delete operations
- **Purpose**: Organize multiple scripts and manage project structure like a real IDE
- **Trigger**: Always visible on desktop, accessible via tabs on mobile
- **Progression**: User clicks "New File" → enters name → new file appears in tree → clicks to open
- **Success criteria**: Files persist between sessions, operations work smoothly, selected file highlights

### Multi-File Tabs
- **Functionality**: Horizontal tabs showing open files with close buttons
- **Purpose**: Work with multiple scripts simultaneously without losing context
- **Trigger**: Opening a file from tree adds a tab
- **Progression**: User opens file → tab appears → clicks tab to switch → clicks X to close
- **Success criteria**: Active tab highlighted, tab state persists, smooth switching

### Multi-Platform Preview
- **Functionality**: Modal showing Roblox, Web, and Mobile viewports side-by-side with shared state sync
- **Purpose**: Visualize how game runs across all platforms simultaneously
- **Trigger**: User clicks "Preview" button in toolbar
- **Progression**: Click Preview → modal opens → see three viewport mockups → view synced state table → close modal
- **Success criteria**: Modal is visually impressive with glassmorphism, state sync table updates, deploy buttons present

### New Project Wizard
- **Functionality**: 3-step modal for creating projects with templates, platform selection, and feature toggles
- **Purpose**: Quick-start new games with appropriate scaffolding
- **Trigger**: User clicks "New Project" button in toolbar
- **Progression**: Click New Project → choose template → configure settings → review → create → file tree populates
- **Success criteria**: Stepper UI shows progress, all template types available, settings persist

### Console Output Panel
- **Functionality**: Bottom panel showing logs filtered by platform (Roblox/Web/Mobile/System)
- **Purpose**: Display runtime output and errors from all platforms in one place
- **Trigger**: Always visible on desktop (collapsible), shows logs automatically
- **Progression**: Code runs → logs appear → filter by platform → clear logs button
- **Success criteria**: Color-coded messages, platform badges, auto-scroll, clear functionality

### User Profile Menu
- **Functionality**: Avatar dropdown in toolbar showing GitHub profile with sign-out option
- **Purpose**: Display current user identity and provide account actions
- **Trigger**: Click avatar icon in top-right
- **Progression**: User logged in → avatar shows → click opens menu → see profile info
- **Success criteria**: Fetches real GitHub user via spark.user(), displays avatar and email

## Edge Case Handling
- **Empty File Tree**: Show placeholder with "Create your first file" message
- **No Open Files**: Display welcome message in editor area
- **AI Errors**: Display user-friendly error messages if AI service is unavailable
- **Large Scripts**: Monaco handles large files, warn if exceeds 10,000 lines
- **Invalid Operations**: Prevent deleting root folder, renaming to empty string
- **Network Issues**: Show offline indicator if can't reach AI or user services
- **Mobile Layout**: Stack panels vertically with tab navigation for Files/Editor/AI

## Design Direction
The design should evoke a professional game development IDE with futuristic gaming aesthetics - dark themes with vibrant cyan/purple accents, glassmorphism effects in modals, and smooth panel animations. This is VS Code meets Unreal Engine editor with a playful gaming twist.

## Color Selection
A dark, code-focused theme with vibrant accent colors inspired by Roblox's playful brand and gaming aesthetics.

- **Primary Color**: oklch(0.45 0.20 265) - Deep electric blue that represents technical precision and digital creativity
- **Secondary Colors**: 
  - Background: oklch(0.15 0.02 265) - Near-black with subtle blue tint
  - Surface: oklch(0.20 0.03 265) - Slightly elevated dark panels
- **Accent Color**: oklch(0.75 0.20 150) - Vibrant cyan-green for CTAs, highlights, and active states
- **Foreground/Background Pairings**: 
  - Primary (Deep Blue): White text (oklch(0.98 0 0)) - Ratio 7.2:1 ✓
  - Accent (Cyan-Green): Dark text (oklch(0.15 0.02 265)) - Ratio 8.1:1 ✓
  - Background (Near-Black): Light text (oklch(0.85 0.03 265)) - Ratio 12.3:1 ✓
  - Surface (Dark Panel): Light text (oklch(0.85 0.03 265)) - Ratio 10.5:1 ✓

## Font Selection
Typography should feel technical yet approachable - monospace for code, clean sans-serif for UI.

- **Typographic Hierarchy**:
  - H1 (App Title): Space Grotesk Bold/32px/tight tracking (-0.02em)
  - H2 (Section Headers): Space Grotesk Semibold/20px/normal tracking
  - Body (UI Text): Inter Medium/14px/relaxed line-height (1.6)
  - Code (Editor): JetBrains Mono Regular/14px/monospace
  - Small (Hints): Inter Regular/12px/muted color

## Animations
Animations should feel snappy and technical - quick state transitions with subtle easing that reinforces the digital tool aesthetic. Use framer-motion for panel slides and modal appearances, but keep transitions under 200ms to avoid feeling sluggish. Add micro-interactions on buttons (scale on press) and smooth scrolling in the chat panel.

## Component Selection
- **Components**: 
  - `Button` with accent variant for primary actions (New Project, Preview)
  - `Card` for template previews, project configs, and preview mockups
  - `Dialog` for Preview Modal, New Project Modal, About dialog
  - `DropdownMenu` for file context menus and user profile menu
  - `Avatar` for user profile display
  - `ScrollArea` for file tree, chat messages, console logs
  - `Tabs` for template categories, preview modes, console filters, mobile navigation
  - `Input` for file rename, project name entry
  - `Checkbox` for platform selection in new project
  - `Switch` for Nexus Engine and Passport Auth toggles
  - `Badge` for popular templates, platform indicators, status labels
  - `Tooltip` for button explanations and feature descriptions
  - `ResizablePanel` for adjustable sidebar and panel widths
  - Custom Monaco Editor wrapper
  - Custom FileTree with nested folders
  - Custom FileTabs with close buttons
  - Custom ConsolePanel with platform filtering
- **Customizations**: 
  - Monaco editor with dark theme configuration
  - File tree with expand/collapse animations
  - Preview modal with glassmorphism effects (backdrop-blur)
  - Multi-platform viewport mockups with device frames
  - Shared state sync table with color-coded status
  - Console with platform-specific badge colors
- **States**: 
  - Buttons: Accent primary (New Project), Ghost secondary (Templates, Copy)
  - File items: Selected (accent background), Hover (muted background)
  - Tabs: Active (accent bottom border), Inactive (transparent)
  - Console logs: Color by type (red error, yellow warn, blue info)
- **Icon Selection**: 
  - File tree: `<Folder />`, `<File />`, `<Plus />`, `<Trash />`, `<PencilSimple />`
  - Toolbar: `<FolderPlus />` (New Project), `<Play />` (Preview), `<User />` (Profile)
  - Preview: `<ArrowsClockwise />` (Refresh), `<GameController />`, `<Globe />`, `<DeviceMobile />`
  - Console: `<Terminal />` (Console icon)
  - All from Phosphor Icons
- **Spacing**: 
  - Container padding: p-4
  - Panel borders: border-border (1px)
  - Component gaps: gap-4 for sections, gap-2 for grouped items
  - File tree indent: 12px per level
- **Mobile**: 
  - Tabs for Files/Editor/AI switching on mobile
  - File tree full-screen on mobile
  - Hide console panel on mobile
  - Preview modal scrollable on small screens
  - Stepper in New Project modal scales down