Nebula-OS/README.md

# Nebula OS v0 – Windows-first Development Plan

## Nebula Shell Prototype (Current)

This repository now includes a working v0 Nebula Shell prototype in the Tauri frontend (`src/`) with:

- Lock Screen with controller/keyboard PIN keypad (`1234` for v0)
- Home dashboard tile grid (Library, Settings, Power)
- Settings split-pane stub (category list + content panel)
- Library stub view with controller back behavior
- Start/Menu power overlay that traps focus and closes with Back
- Unified input actions (`up/down/left/right/accept/back/menu`) from keyboard + gamepad

### Dashboard refresh (Xbox-inspired Nebula)

The shell now uses a premium horizontal dashboard language inspired by console UI patterns:

- Left-aligned horizontal app tile rail (Library, Settings, Power)
- Dynamic nebula background stack (gradient, starfield, fog, vignette)
- Shared top bar with reactive accent line and profile/time status
- Layered tile focus states (scale, cyan glow, ripple, elevation)
- Smooth page/focus transitions with cubic-bezier motion curves
- Immersive lock screen with large clock/date and input-revealed PIN panel
- Settings redesign with top category rail + card-based content panel

Animation and component architecture notes are in [src/styles/shell-guidelines.md](src/styles/shell-guidelines.md).

### Install

```bash
npm install
```

### Run (Windows dev)

```bash
npm run dev
```

### Build

```bash
npm run build
```

### Controller testing notes (Windows)

- Connect an Xbox-compatible controller before launching dev mode.
- Navigation: D-pad or left stick.
- Actions: `A` = Accept, `B` = Back, `Start` = Menu.
- Keyboard mirror for development: arrow keys, Enter, Escape/Backspace.

### Nebula Core integration status

`@nebulaproject/core` is installed and used through runtime adapters in:

- `src/core/input.js`
- `src/core/nav.js`
- `src/core/state.js`

If Nebula Core exports are available, the shell uses them for input/navigation/glyphs/theme.
If not, local fallback adapters keep the shell fully functional.

### Local Nebula Core development (Windows-safe)

Current npm package `@nebulaproject/core@0.1.3` re-exports internal `@nebula/*` packages that are not published, so local linking is recommended for active core development.

1. Clone Nebula Core monorepo next to this repo.
2. Build Nebula Core packages.
3. Link from the core repo and consume in this repo:

```bash
# In Nebula-Core repo
npm link

# In Nebula-OS repo
npm link @nebulaproject/core
```

Alternative (more deterministic): use `file:` dependency in `package.json`:

```json
{
  "dependencies": {
    "@nebulaproject/core": "file:../Nebula-Core/packages/core"
  }
}
```

Then run:

```bash
npm install
```

### Linux VM build (high-level)

- Install Rust, Node.js, and Tauri Linux prerequisites in the VM.
- Clone this repo in Linux VM.
- Run `npm install`.
- Run `npm run dev` for integration checks in Linux session.
- Run `npm run build` to produce Linux artifacts.

## Vision

Nebula OS is a **controller-first, open source operating system experience** built on Linux.

It has two equally important jobs:

1. **A custom controller-first way to navigate the OS** (like a console shell)
2. **An open source library and launcher layer** for games and apps

Nebula OS is not a skin that launches Steam.
It is an independent UI layer that:

* Acts as the primary **controller-first shell** for the OS
* Provides a unified Home experience for **games, apps, and media**
* Integrates first-install Nebula apps such as **Nebula Browser** and **Nebula Launcher**
* Exposes **system settings** through controller-friendly panels
* Manages game libraries directly (Steam, GOG, Epic, and others)

Nebula OS v0 focuses on building the foundation for this console-grade OS shell.

---

# Core Principles

1. Controller-first, not controller-compatible
2. Replace proprietary frontends with an open interface
3. Separate system layer from UI layer
4. Build modular infrastructure for long-term independence
5. Develop iteratively, but architect for autonomy

---

# What Nebula OS v0 Actually Is

Nebula OS v0 consists of:

* Base OS: Ubuntu LTS (or Ubuntu-based)
* Desktop Environment: KDE Plasma (recommended)
* Display Manager: SDDM
* Two login sessions:

  * Nebula Desktop
  * Nebula Game UI
* Nebula Shell (Tauri + HTML/CSS/JS)
* Nebula Library (core application responsible for:

  * Game discovery
  * Installation
  * Updates
  * Launching
  * Compatibility management)

Unlike SteamOS, Nebula OS does not rely on launching Steam Big Picture.
Nebula Library is the primary game management layer.

---

# High-Level Architecture

## Desktop Mode

A standard KDE session for:

* Productivity workflows
* File browsing and system tools
* Development and troubleshooting
* Advanced configuration

Desktop Mode remains a normal Linux desktop.

## Game UI Mode

A dedicated login session that launches **Nebula Shell** fullscreen.

Game UI Mode contains:

* Lock screen with controller PIN entry
* Nebula Home dashboard
* Nebula Library
* Controller-friendly Settings
* Power and session controls

Game UI Mode is the **console experience** for the entire OS.

## System Integration Layer (behind the UI)

Nebula OS needs a clean boundary between UI and system operations.

Recommended approach:

* A small privileged backend service (later) that exposes safe operations:

  * Wi-Fi and networking
  * Audio and output device selection
  * Display resolution and scaling
  * Bluetooth pairing
  * Storage overview
  * Power controls
* The UI talks to that layer through a stable API

v0 scope can start with non-privileged read-only data and a few safe commands.

---

# Technology Stack

## UI Layer

* Tauri
* HTML
* CSS
* JavaScript

Why Tauri:

* Lightweight
* Native system integration via Rust backend
* Cross-platform development
* Efficient resource usage

## Controller Input

* Web Gamepad API
* Custom focus/navigation system

Controller mappings:

* D-pad / left stick: navigation
* A: activate
* B: back
* Start: menu
* Shoulder buttons: future navigation layers

Keyboard mirrors controller during development.

---

# Nebula Shell – The OS UI Layer

Nebula Shell is the **controller-first OS shell**.

It is the primary interface in Game UI Mode and should feel like a console dashboard, not a desktop.

Nebula Shell responsibilities:

* Home dashboard (games, apps, recent activity)
* App launcher for integrated Nebula apps (Nebula Browser, Nebula Launcher, Nebula Library, Settings)
* System navigation (network, audio, display, storage, accounts)
* Power menu and session switching (Game UI ↔ Desktop)
* Notifications and downloads (later)
* Controller-first focus navigation everywhere

Nebula Shell is built with Tauri + HTML/CSS/JS.

---

# Nebula Library – The Game and App Management Layer

Nebula Library is the **content manager** inside Nebula OS.

It is not a bridge to proprietary UIs.
It should eventually handle:

* Steam installs via SteamCMD and/or open APIs
* GOG installs via open or community tooling
* Epic installs via open tooling (for example Legendary)
* Proton/Wine configuration and per-title settings
* Game launch parameters and runtime selection
* Updates, integrity checks, and metadata

Initial v0 scope:

* Library UI skeleton and data model
* Local entries (manual add)
* Launch local executables
* Foundation for compatibility and store backends

Long-term direction:

Nebula Library becomes a unified open source platform for managing games and apps.

---

# Development Strategy

Nebula OS is developed in two environments:

## Windows (Primary UI Development)

Used for:

* Building Nebula Shell UI
* Implementing controller navigation
* Designing lock screen
* Designing Library UI
* Building system state architecture

UI and logic are platform-agnostic.

## Linux VM (Integration & Replacement Layer)

Used for:

* Building Linux binaries
* Session integration
* SteamCMD integration testing
* Proton/Wine configuration
* System-level testing

Rule:

Develop UI on Windows.
Build and test Linux features inside the VM.

---

# Phase Roadmap

## Phase 1 – Nebula Shell (Controller Console Layer)

Objective:
Build a polished, console-grade Game UI independent of store integration.

Deliverables:

* Lock screen with PIN keypad
* Home dashboard
* Library screen (mock data)
* Settings screen
* Power menu
* Controller navigation grid system
* Fullscreen window behavior

No external integrations yet.

---

## Phase 2 – Session Integration

Objective:
Make Nebula Shell a selectable login session.

Milestones:

* Nebula Game UI appears at login
* Launches fullscreen
* Exiting returns to login
* Controller works reliably

---

## Phase 3 – Nebula Library Foundations

Objective:
Begin true replacement behavior.

Milestones:

* Launch local Linux games
* Integrate Proton/Wine execution layer
* Add SteamCMD support for installing Steam titles
* Track installed game metadata
* Unified library view

This is where Nebula begins diverging from SteamOS.

---

## Phase 4 – Store Integrations

Objective:
Add real backend integration without proprietary UI.

Potential directions:

* SteamCMD for Steam installs
* Legendary (Epic CLI) integration
* Heroic backend reuse (without UI dependency)
* OpenGOG community tools

Nebula Library becomes the single UI.

---

# Security Strategy

Game UI lock screen:

* Local PIN authentication
* Optional profile system (future)

Linux account authentication remains system-level.

---

# What Nebula OS Is Not

* Not a Steam skin
* Not Big Picture mode
* Not a launcher aggregator
* Not dependent on proprietary UIs

It is an open system layer that manages games directly.

---

# Immediate Action Plan

1. Build Nebula Shell UI on Windows
2. Implement controller navigation framework
3. Build lock screen system
4. Build Library UI skeleton
5. Set up Linux VM
6. Create Nebula Game UI login session
7. Begin local executable launching support
8. Research SteamCMD integration

---

# Success Criteria for v0

Nebula OS v0 is successful when:

* You can log into Nebula Game UI
* The entire UI is controller navigable
* Lock screen works
* You can launch locally managed games
* You can return to Desktop Mode

From there, Nebula Library evolves into a true open source game management platform.