You are an expert AI assistant tasked with building a single-page web application (SPA) that allows users to run various operating systems within their browser. The application, codenamed 'BrowserOS', aims to provide an instant, sandboxed environment for development, testing, and educational purposes without requiring any local installation. Your goal is to generate a fully functional frontend application based on the provided specifications.
**1. PROJECT OVERVIEW:**
BrowserOS allows users to select and run different operating systems (e.g., Linux distributions, DOS) directly in their web browser using emulation technology. The core value proposition is providing an accessible, zero-installation, sandboxed environment for developers, students, and testers to experiment with different OS environments, run legacy software, or practice command-line operations. It eliminates the setup overhead and resource requirements of traditional virtual machines.
**2. TECH STACK:**
- **Frontend Framework:** React (using functional components and hooks)
- **Styling:** Tailwind CSS for rapid and utility-first styling.
- **State Management:** Zustand for efficient and simple global state management. Local state will be managed using `useState` and `useReducer` where appropriate.
- **Routing:** React Router DOM for navigation within the single-page application (if multiple views are deemed necessary, though the MVP aims for a single primary view).
- **Emulation Library:** Integrate with a suitable JavaScript-based emulation library like JSLinux's core components or a similar WASM-based solution if available and performant. For this prompt, assume we are integrating with a hypothetical `BrowserEmulator` JS library that handles the OS booting and interaction.
- **UI Components:** Utilize a library like `react-icons` for icons and potentially custom-built components for a unique look and feel.
- **Build Tool:** Vite for fast development server and optimized builds.
**3. CORE FEATURES:**
* **OS Selection:**
* **User Flow:** Upon landing on the page, the user is presented with a list of available operating systems (e.g., 'Alpine Linux x86_64', 'FreeDOS VGA Text', 'Windows 2000 Graphical'). Each OS option displays its name, a brief description, and potentially an icon.
* **Interaction:** The user clicks on their desired OS. The application then initiates the setup and loading process for the selected OS within the browser.
* **OS Emulation & Interaction:**
* **User Flow:** Once an OS is selected, the emulation begins. A dedicated area on the page displays the emulated OS output (either graphical or text-based console).
* **Interaction:** For console-based OS, users can type commands directly into an input field or directly into the emulated terminal. For graphical OS, users can interact via mouse clicks and keyboard input mapped to the emulated environment. The `BrowserEmulator` library will handle input capturing and OS-level event simulation.
* **Session Management (MVP):**
* **User Flow:** The application tracks the active emulation session. Users can see the status of their running OS.
* **Interaction:** A button or control allows the user to terminate the current emulation session. Upon termination, the emulated environment is reset, and any temporary data is cleared.
* **Basic Configuration (Optional MVP Enhancement):**
* **User Flow:** Before launching an OS, users might have a simple modal or section to adjust minimal settings (e.g., selecting text vs. graphical mode if available for an OS).
* **Interaction:** User selects desired options, then proceeds to launch.
**4. UI/UX DESIGN:**
* **Layout:** Single-page application. A clean, modern, and intuitive interface. The main view will feature:
1. A header with the application title and potentially user authentication/settings options.
2. A central area displaying the OS selection grid or list.
3. An integrated area (modal or dedicated section) where the emulated OS console/GUI will be rendered once launched.
4. A footer with links to About, FAQ, and potentially technical notes.
* **Color Palette:** A dark theme primary palette to evoke a 'hacker' or 'developer' aesthetic, with a contrasting accent color for interactive elements. Example: Primary: `#1a1a1a` (Dark Gray), Secondary: `#2c2c2c` (Slightly Lighter Gray), Accent: `#00ff85` (Electric Green) or `#4ade80` (Emerald Green).
* **Typography:** Use a clean, readable sans-serif font for UI elements (e.g., 'Inter', 'Roboto') and a monospace font for the emulated terminal output (e.g., 'Fira Code', 'Source Code Pro').
* **Responsive Design:** The application must be fully responsive. On smaller screens, the OS selection grid might become a list, and the emulation area will take up the majority of the screen. Ensure usability across desktops, tablets, and mobile devices.
* **Loading States:** Implement clear loading indicators (spinners, progress bars) during OS boot-up and transitions.
* **Error Handling:** Display user-friendly error messages if an OS fails to load or an emulation error occurs.
**5. DATA MODEL:**
* **`osList`:** An array of objects, defining the available operating systems.
```javascript
[
{
id: 'x86_64-alpine-3.23.2',
name: 'Alpine Linux x86_64',
description: 'With AVX-512 and APX support.',
type: 'console',
imageUrl: '/images/alpine.png' // Optional icon
},
{
id: 'x86-freedos',
name: 'FreeDOS VGA Text',
description: 'Classic DOS environment.',
type: 'console',
imageUrl: '/images/freedos.png'
},
{
id: 'x86-win2k',
name: 'Windows 2000 Graphical',
description: 'Legacy Windows environment.',
type: 'graphical',
imageUrl: '/images/win2k.png'
},
// ... more OS definitions
]
```
* **`emulatorState`:** Global state managed by Zustand.
```javascript
{
selectedOsId: null | string, // ID of the currently selected OS
currentOsInfo: null | object, // Detailed info of the selected OS
isLoading: boolean, // Whether an OS is currently booting
isEmulating: boolean, // Whether an emulation session is active
error: null | string, // Any error message
// Potentially terminal output buffer or screen state for graphical
terminalOutput: string[], // For console
screenBuffer: any // For graphical (simplified)
}
```
* **Local Storage:** Use `localStorage` for persisting user preferences (e.g., last selected OS) if desired for a smoother UX, but not critical for MVP functionality.
**6. COMPONENT BREAKDOWN:**
* **`App.jsx`:** Main application component. Sets up routing (if any), global layout, and context providers.
* **`Header.jsx`:** Displays the application title and navigation/user elements.
* Props: `title` (string)
* **`OsSelector.jsx`:** Renders the grid/list of available OS options.
* Props: `osList` (array), `onSelectOs` (function)
* **`OsCard.jsx`:** Represents a single OS option in the selector.
* Props: `os` (object - containing id, name, description, type, imageUrl), `onClick` (function)
* **`EmulatorWindow.jsx`:** The main area where the emulated OS runs. This component will likely contain or manage the `BrowserEmulator` instance.
* Props: `osId` (string | null), `onBootComplete` (function), `onError` (function), `onCommand` (function), `onExit` (function)
* **`Terminal.jsx`:** Renders a text-based terminal interface within the `EmulatorWindow`.
* Props: `output` (array of strings), `onInput` (function), `isLoading` (boolean)
* **`GraphicalDisplay.jsx`:** Renders the graphical output for OS like Windows 2000 (if implemented).
* Props: `screenBuffer` (any), `onClick` (function), `onKeyboardInput` (function)
* **`LoadingSpinner.jsx`:** A simple, reusable loading indicator component.
* **`ErrorMessage.jsx`:** Displays error messages to the user.
* Props: `message` (string)
* **`EmulatorControls.jsx`:** Buttons for starting, stopping, and potentially other controls for the emulation.
* Props: `onStart`, `onStop`, `isRunning` (boolean)
**7. ANIMATIONS & INTERACTIONS:**
* **OS Card Hover:** Subtle scale-up or background color change on `OsCard` hover using Tailwind's `hover:` variants.
* **Page Transitions:** Fade-in/fade-out transitions between different sections or states (e.g., from OS selection to emulation view) using libraries like `Framer Motion` or simple CSS transitions.
* **Loading Animation:** Smoothly animating `LoadingSpinner` while an OS is booting.
* **Terminal Input:** Smooth scrolling for terminal output as new lines are added.
* **Button Interactions:** Subtle `active:` or `focus:` states for buttons using Tailwind.
**8. EDGE CASES:**
* **No OS Selected:** The `EmulatorWindow` should display a placeholder message prompting the user to select an OS.
* **Loading Failures:** If `BrowserEmulator.load()` fails, display a clear, user-friendly error message via `ErrorMessage.jsx` and reset the state.
* **Emulation Errors:** Catch errors during emulation (`BrowserEmulator.run()`) and display them.
* **Empty Terminal:** Handle the initial state of the terminal before any output is received.
* **Input Validation:** Ensure user input for commands is handled correctly by the emulator and not causing crashes.
* **Resource Limits:** If the underlying emulation technology has limits (e.g., memory, CPU time), consider how to inform the user or gracefully degrade functionality. (This is more backend/emulation logic but frontend should reflect it).
* **Accessibility (a11y):** Use semantic HTML elements, ensure sufficient color contrast, provide ARIA attributes where necessary (e.g., for the terminal input), and ensure keyboard navigability.
**9. SAMPLE DATA:**
* **`osList` Sample:**
```javascript
[
{
id: 'x86_64-alpine-3.23.2',
name: 'Alpine Linux x86_64',
description: 'Lightweight Linux distribution. Console-only.',
type: 'console',
imageUrl: '/icons/alpine.svg'
},
{
id: 'x86-win2k',
name: 'Windows 2000',
description: 'Classic graphical Windows environment.',
type: 'graphical',
imageUrl: '/icons/win2k.svg'
},
{
id: 'x86-freedos',
name: 'FreeDOS',
description: 'MS-DOS compatible OS. Text-based.',
type: 'console',
imageUrl: '/icons/freedos.svg'
},
{
id: 'riscv64-fedora-33',
name: 'Fedora 33 (RISC-V)',
description: 'Modern Linux on RISC-V architecture. Longer boot time.',
type: 'console',
imageUrl: '/icons/fedora.svg'
}
]
```
* **`emulatorState` Initial State:**
```javascript
{
selectedOsId: null,
currentOsInfo: null,
isLoading: false,
isEmulating: false,
error: null,
terminalOutput: ['Welcome to BrowserOS! Select an OS to begin.']
}
```
* **`terminalOutput` Example (Alpine Linux):**
```javascript
[
'Welcome to Alpine Linux 3.23.2 (kernel ...) ...',
'# Your login: root',
'# Password: /* Password input hidden */',
'Welcome to Alpine!',
'# ls -la',
'total 48',
'drwxr-xr-x 1 root root 4096 Jan 1 1970 .',
'drwxr-xr-x 1 root root 4096 Jan 1 1970 ..',
// ... more output lines
'# ' // Prompt for next command
]
```
**10. DEPLOYMENT NOTES:**
* **Build Command:** Use `npm run build` (or `yarn build`) configured via Vite for optimized production builds.
* **Environment Variables:** Utilize `.env` files for managing environment variables (e.g., `VITE_EMULATOR_API_ENDPOINT` if the emulator logic is server-based, though for this SPA it's likely client-side WASM/JS).
* **Performance Optimizations:**
* Code Splitting: Vite handles this automatically for different routes or components.
* Memoization: Use `React.memo` for expensive component re-renders.
* Efficient State Updates: Leverage Zustand's selectors and avoid unnecessary re-renders.
* Bundle Size: Be mindful of the size of the emulation library; consider lazy loading it if possible.
* **Hosting:** The static build can be deployed to any static hosting provider (Netlify, Vercel, GitHub Pages, AWS S3).
* **HTTPS:** Ensure deployment uses HTTPS for security.