PROJECT OVERVIEW:
Build a native macOS desktop application named 'Linux Desktop Bridge' that acts as a seamless integration layer for running Linux GUI applications directly on macOS. This application leverages the Wayland protocol and a custom client-server architecture (waypipe) to stream Linux application windows to the macOS desktop without the overhead of traditional virtual machines or containers. The core value proposition is providing a zero-VM, high-performance, and deeply integrated experience for macOS users who need to run specific Linux applications.
Target Audience: macOS users who frequently need to use Linux GUI applications for development, data science, research, or other technical tasks. They are likely familiar with tools like OrbStack, Docker Desktop, or VMs but seek a more integrated and performant solution.
TECH STACK:
- Frontend/Desktop App: Next.js (App Router) for the management UI, possibly integrating with a native macOS UI framework like SwiftUI or AppKit via bridges if needed for the compositor itself, but the prompt focuses on the Next.js aspect for the management interface.
- Styling: Tailwind CSS for rapid UI development.
- Backend/Compositor Logic: Rust (using Cargo for build and dependency management) for the core Wayland compositor (Cocoa-Way) and the waypipe client. This part will be compiled into a native macOS binary.
- Database (for user settings/profiles): Drizzle ORM with a local SQLite database (or PostgreSQL if a cloud sync feature were added later, but MVP is local) managed by the Next.js backend.
- UI Components: shadcn/ui for pre-built, accessible, and customizable UI components.
- Authentication: NextAuth.js for managing user accounts and preferences within the Next.js app (if cloud sync is ever considered, for MVP local storage is sufficient).
- State Management: React Context API / Zustand for the Next.js frontend. Rust's internal state management for the compositor.
DATABASE SCHEMA (Local SQLite for Next.js App Settings):
- `users` table (if auth is implemented for settings sync, otherwise omit for MVP):
- `id` (TEXT, PK)
- `name` (TEXT)
- `email` (TEXT, UNIQUE)
- `image` (TEXT)
- `linux_apps` table:
- `id` (TEXT, PK)
- `name` (TEXT) - e.g., 'Firefox', 'VS Code'
- `command` (TEXT) - e.g., 'firefox', 'code --ozone-platform-hint=auto'
- `waypipe_host` (TEXT) - e.g., 'localhost', 'user@remote-ip'
- `waypipe_port` (INTEGER)
- `created_at` (INTEGER)
- `updated_at` (INTEGER)
- `profiles` table (for saving connection/app configurations):
- `id` (TEXT, PK)
- `name` (TEXT) - e.g., 'Development Workstation', 'Remote Server'
- `linux_apps_ids` (TEXT) - JSON or comma-separated string of `linux_apps.id`
- `waypipe_ssh_key_path` (TEXT, optional)
- `created_at` (INTEGER)
CORE FEATURES & USER FLOW:
1. **Compositor Service (Rust Backend):**
* **User Flow:** This service runs in the background, managed by the macOS binary. It initializes a Wayland server and listens for incoming connections from the `waypipe` client.
* **Functionality:** Receives Wayland protocol events, processes them, and renders them to the macOS display using Metal/OpenGL. Handles window management, focus, shadows, and HiDPI scaling.
* **Edge Cases:** Startup errors, Wayland protocol errors, rendering pipeline failures.
2. **Waypipe Client Integration (Rust Binary):**
* **User Flow:** The user installs `waypipe-darwin`. The `Linux Desktop Bridge` app will launch `cocoa-way` (the compositor) and then execute the `waypipe` command to connect a specified Linux application.
* **Functionality:** Connects to the running `cocoa-way` compositor via a Unix socket or TCP. Forwards Wayland protocol data between the Linux application (running potentially on a remote machine or in a container accessible via SSH) and the macOS compositor. Handles SSH connections if remote Linux apps are targeted.
* **Command Example:** `cocoa-way` (starts compositor) followed by `./run_waypipe.sh ssh user@linux-host firefox` (executed via the Next.js app's spawn process functionality).
* **Edge Cases:** SSH connection failures, `waypipe` not found, incorrect host/user details.
3. **Next.js Management UI:**
* **User Flow (Add Linux App):** User navigates to 'My Linux Apps' -> 'Add New App'. Fills a form with App Name (e.g., 'Firefox'), Command (e.g., 'firefox --ozone-platform-hint=auto'), Waypipe Host (e.g., 'localhost' or 'user@remote-ip'). Clicks 'Save'.
* **User Flow (Launch App):** User sees a list of saved Linux Apps. Clicks the 'Play' button next to 'Firefox'. The Next.js app triggers a backend process to start `cocoa-way` (if not running) and then execute the `waypipe` command: `ssh user@linux-host firefox`.
* **User Flow (Manage Profiles):** User navigates to 'Profiles'. Creates a new profile (e.g., 'Work Dev Environment'), selects multiple saved Linux Apps to include in this profile. Saves the profile. Later, launches all apps in the profile with a single click.
* **Functionality:** Provides a dashboard, lists saved Linux Apps, allows adding/editing/deleting apps, manages connection profiles, starts/stops Linux application streams, displays connection status, and potentially shows logs.
* **Edge Cases:** Form validation errors, saving/loading settings, process management (starting/stopping spawned processes), display of connection status.
API & DATA FETCHING (Next.js App):
- **`/api/apps` (GET):** Fetches the list of saved Linux applications from the local database.
- **`/api/apps` (POST):** Adds a new Linux application configuration to the database.
- **`/api/apps/[id]` (PUT):** Updates an existing Linux application configuration.
- **`/api/apps/[id]` (DELETE):** Deletes a Linux application configuration.
- **`/api/profiles` (GET, POST, PUT, DELETE):** CRUD operations for connection profiles.
- **`/api/apps/launch` (POST):** Body: `{ appId: string }`. Triggers the spawning of the `cocoa-way` compositor and the `waypipe` client process for the given `appId`.
- **`/api/apps/stop` (POST):** Body: `{ appId: string }`. Triggers the termination of the `waypipe` client process associated with `appId`.
- **Data Flow:** React components use `fetch` or a library like `swr` to interact with these API routes. Data is fetched and displayed in tables/lists. User actions trigger API calls, updating the database and potentially the UI in real-time.
COMPONENT BREAKDOWN (Next.js App Router):
- **`app/layout.tsx`:** Root layout, includes global Tailwind CSS, providers (e.g., Zustand store provider), potentially theme toggler.
- **`app/page.tsx`:** Dashboard. Overview of running apps, quick launch buttons, profile selection. Fetches and displays active sessions.
- **`app/apps/page.tsx`:** 'My Linux Apps' page. Displays a `DataTable` component for `linux_apps`. Includes buttons for 'Add New App', 'Edit', 'Delete', 'Launch'.
- **`app/apps/new/page.tsx` & `app/apps/[id]/edit/page.tsx`:** Forms for adding/editing Linux apps. Uses `shadcn/ui` form components. Includes fields for Name, Command, Host, etc. Includes client-side validation.
- **`app/profiles/page.tsx`:** 'Profiles' page. Displays a `DataTable` for `profiles`. Add/Edit/Delete functionality.
- **`app/settings/page.tsx`:** General application settings (e.g., path to `waypipe` binary, compositor launch behavior).
- **`app/components/ui/DataTable.tsx`:** Reusable table component using `shadcn/ui` or `react-table`. Displays app/profile data.
- **`app/components/ui/AppForm.tsx`:** Form component for adding/editing apps.
- **`app/components/ui/ProfileForm.tsx`:** Form component for profiles.
- **`app/components/ui/StatusIndicator.tsx`:** Displays connection status (Connecting, Running, Disconnected) for each app.
- **`app/components/ui/LaunchButton.tsx`:** Button that triggers the launch API.
- **`app/components/ui/StopButton.tsx`:** Button that triggers the stop API.
- **`app/components/layout/Sidebar.tsx`:** Navigation sidebar.
- **`app/components/layout/Header.tsx`:** Application header.
UI/UX DESIGN & VISUAL IDENTITY:
- **Design Style:** Minimalist Clean with a touch of Modern Tech.
- **Color Palette:**
- Primary (Dark Mode): `#1e1e1e` (Background), `#ffffff` (Text), `#4a90e2` (Accent/Buttons)
- Primary (Light Mode): `#f8f9fa` (Background), `#212529` (Text), `#007bff` (Accent/Buttons)
- Secondary Accent: `#50e3c2` (Subtle highlights, loading indicators)
- **Typography:** Inter font family (`'Inter', sans-serif`). Clear hierarchy using font weights and sizes.
- **Layout:** Sidebar navigation on the left, main content area on the right. Use of cards and clear sections for different functionalities (Apps, Profiles, Settings). Max-width container for content.
- **Animations:** Subtle fade-ins for components, smooth transitions on hover effects for buttons and list items. Loading spinners (using `tailwinds-merge` and `react-spinners` or custom SVG) for API calls and process starts.
- **Responsive Rules:** Mobile-first approach for the Next.js UI. Sidebar collapses into a hamburger menu on smaller screens. Content reflows appropriately. The core compositor runs natively and is unaffected, but the management UI must be responsive.
SAMPLE DATA (for `linux_apps` table):
1. `{
"id": "app_123",
"name": "VS Code (Remote)",
"command": "code --ozone-platform-hint=auto --remote-ssh --folder-uri ssh://user@192.168.1.100:/home/user/projects",
"waypipe_host": "user@192.168.1.100",
"created_at": 1678886400,
"updated_at": 1678886400
}`
2. `{
"id": "app_456",
"name": "Firefox (Local)",
"command": "firefox --ozone-platform-hint=auto",
"waypipe_host": "localhost",
"created_at": 1678886500,
"updated_at": 1678886500
}`
3. `{
"id": "app_789",
"name": "GIMP",
"command": "gimp",
"waypipe_host": "localhost",
"created_at": 1678886600,
"updated_at": 1678886600
}`
4. `{
"id": "app_abc",
"name": "Terminal Server",
"command": "/usr/bin/gnome-terminal --full-screen",
"waypipe_host": "dev@server.example.com",
"created_at": 1678886700,
"updated_at": 1678886700
}`
5. `{
"id": "app_def",
"name": "Node-RED UI",
"command": "/usr/bin/node-red-start --ui-port 1880",
"waypipe_host": "localhost",
"created_at": 1678886800,
"updated_at": 1678886800
}`
SAMPLE DATA (for `profiles` table):
1. `{
"id": "prof_1",
"name": "Daily Dev Tools",
"linux_apps_ids": "app_123,app_456",
"created_at": 1678887000,
"updated_at": 1678887000
}`
2. `{
"id": "prof_2",
"name": "Remote Server Admin",
"linux_apps_ids": "app_abc,app_def",
"waypipe_ssh_key_path": "~/.ssh/id_rsa_remote",
"created_at": 1678887100,
"updated_at": 1678887100
}`
ANIMATIONS:
- **Buttons:** Subtle scale-in effect on hover, slight background color change.
- **List Items (Apps/Profiles):** Fade-in on load, slight lift/shadow on hover.
- **Loading States:** Use `react-spinners` (e.g., `PuffLoader`) or custom SVG spinners within buttons or for table loading, with fade transitions.
- **Transitions:** Use `Framer Motion` or Tailwind's transition utilities for smooth state changes (e.g., sidebar collapse, form submissions).
EDGE CASES:
- **First Launch:** If `cocoa-way` or `waypipe-darwin` are not installed, guide the user through installation (linking to brew commands or download page). Provide an option to auto-install dependencies.
- **Permissions:** macOS Gatekeeper/notarization prompts for the native binary. User needs to grant accessibility/input monitoring permissions if required by the compositor.
- **Process Management:** Gracefully handle termination of spawned `cocoa-way` and `waypipe` processes. Prevent multiple instances of `cocoa-way` from starting unnecessarily.
- **Authentication (if implemented for sync):** Handle login/logout flows, token refresh, unauthorized errors.
- **Form Validation:** Implement robust client-side (using libraries like Zod with shadcn/ui forms) and server-side validation for all input fields.
- **Error Handling:** Display user-friendly error messages for failed connections, invalid commands, missing dependencies, or compositor crashes. Log detailed errors for debugging.
- **Empty States:** Display informative messages and clear calls to action when the 'My Linux Apps' or 'Profiles' lists are empty.