# Nebara OS TUI — Visual Baseline v0.1

Native terminal management interface for the **Nebara S3GX Appliance**, implemented in Go using `tview` + `tcell/v2`.

> [!IMPORTANT]
> This is a **visual prototype** using mock appliance data only.
> No real system configuration, privileged operations, or hardware interaction occurs.

---

## Overview

Nebara OS is a common appliance operating environment for enterprise infrastructure products.
This prototype establishes the TUI visual foundation for the Nebara S3GX Appliance,
reproducing the Figma reference mockups as faithfully as a native terminal environment allows.

The interface is intentionally minimal and industrial — inspired by enterprise console UIs like VMware ESXi DCUI.

---

## Prerequisites

| Requirement | Version |
|---|---|
| Go | ≥ 1.21 |
| Terminal | True-color 256+ color support |
| Recommended font | JetBrains Mono (any weight) |

### Check Go version

```bash
go version
```

---

## Build

```bash
git clone <repo>
cd nebara-os
go mod tidy
go build -o nebara-tui ./cmd/nebara-tui
```

On Windows:

```powershell
go build -o nebara-tui.exe ./cmd/nebara-tui
```

---

## Run

```bash
# Warning state (default) with SIXEL logo
./nebara-tui --mock-state=warning --sixel=true

# Normal state with SIXEL logo
./nebara-tui --mock-state=normal --sixel=true

# Fallback to pure text colored logo
./nebara-tui --sixel=false
```

Or via `go run`:

```bash
go run ./cmd/nebara-tui --mock-state=warning --sixel=true
go run ./cmd/nebara-tui --mock-state=normal --sixel=false
```

---

## Mock States

### State A — Warning (`--mock-state=warning`)

| Field | Value |
|---|---|
| Product | Nebara S3GX Appliance |
| Version | 1.0.1 |
| Hostname | jkt-s3gx-lin-01.domain.local |
| Address | 10.249.23.13/26 |
| Uptime | 132d 12h 32m |
| Status | Healthy |
| Message | `[Warn] Update Available to version 2.1.4!` |
| Initial selection | Security & Access |

### State B — Normal (`--mock-state=normal`)

| Field | Value |
|---|---|
| Product | Nebara S3GX Appliance |
| Version | 2.1.4 |
| Hostname | sin-s3gx-lin-05.domain.local |
| Address | 10.175.15.11/25 |
| Uptime | 111d 14h 21m |
| Status | Healthy |
| Message | None |
| Initial selection | System Maintenance |

---

## Keyboard Controls

| Key | Action |
|---|---|
| `↑` / `↓` | Navigate menu items |
| `Enter` | Open submenu or confirm |
| `Esc` | Return to parent menu |
| `Home` | Jump to first item |
| `End` | Jump to last item |
| `F1` | Show keyboard shortcut help |
| `Ctrl+C` | Quit application |

---

## Recommended Terminal Settings

For the best visual experience:

- **Font:** JetBrains Mono (Regular / Bold) — available from [jetbrains.com/lp/mono](https://www.jetbrains.com/lp/mono/)
- **Color support:** True-color (24-bit) — set `COLORTERM=truecolor` if needed
- **Background:** Black (`#000000`) — ensure terminal background matches
- **Minimum size:** 60 columns × 20 rows (warning shown if smaller)
- **Recommended size:** 120 columns × 40 rows or larger

### Windows Terminal

```json
{
  "font": { "face": "JetBrains Mono", "size": 14 },
  "colorScheme": "One Half Dark"
}
```

Set `COLORTERM=truecolor` in your shell profile for 24-bit colors.

---

## Responsive Layout

The layout adapts to terminal dimensions using percentage-based margins derived from the Figma reference (1920×1080, 80px outer margins ≈ 4.17% of width):

| Terminal Size | Behavior |
|---|---|
| 192×54 and wider | Spacious; full Figma proportions |
| 120×40 | Normal desktop; full metadata |
| 100×30 | Compact; reduced whitespace |
| 80×24 | Minimum practical target; message row suppressed below 24 rows |
| Below 60×20 | Size warning overlay; no crash |

Live resizing is handled; no restart required.

---

## Project Structure

```
nebara-os/
├── cmd/
│   └── nebara-tui/
│       └── main.go              # CLI entry point, --mock-state flag
│
├── internal/
│   ├── app/
│   │   ├── application.go       # TUI wiring: layout, callbacks, modals
│   │   └── state.go             # Runtime application state struct
│   │
│   ├── model/
│   │   ├── appliance.go         # ApplianceInfo data model
│   │   ├── message.go           # SystemMessage + severity types
│   │   └── menu.go              # MenuItem tree + MainMenu() factory
│   │
│   ├── ui/
│   │   ├── theme/
│   │   │   └── colors.go        # Centralized color tokens & tcell styles
│   │   │
│   │   ├── layout/
│   │   │   └── responsive.go    # Terminal→cell layout constraint calculator
│   │   │
│   │   ├── components/
│   │   │   ├── header.go        # Header, ApplianceInfo, Message, Description, Footer
│   │   │   └── menu.go          # Custom MenuWidget (full-width row highlight)
│   │   │
│   │   └── navigation/
│   │       └── navigator.go     # Navigation stack (Enter/Back/Up/Down)
│   │
│   └── mock/
│       └── states.go            # WarningState() and NormalState() factories
│
├── go.mod
├── go.sum
└── README.md
```

---

## Design System

### Colors

| Token | Hex | Usage |
|---|---|---|
| Background | `#000000` | Main screen background |
| Primary | `#F5F5F5` | Default foreground text |
| Secondary | `#BBBBBB` | Labels, descriptions, borders |
| Selection BG | `#BBBBBB` | Selected menu row background |
| Selection FG | `#000000` | Selected menu row text |
| Warning | `#FFCC00` | Warning message text |
| Error | `#B30D18` | Error messages; logo "O" accent |
| Info | `#0088FF` | Informational messages |

### Typography Hierarchy

The terminal cannot control font family per-component. Hierarchy is expressed through:

- **Bold** — product title, footer key labels
- **Regular** — metadata labels, values, menu items, descriptions
- **Color** — severity-classified messages, logo accent

---

## Known Terminal Rendering Limitations

| Figma Specification | Terminal Equivalent |
|---|---|
| Michroma 24px logo font | Terminal monospace font; layout preserved |
| JetBrains Mono Bold/Regular by size | Bold attribute; font configured per-terminal |
| 1px border (outside alignment) | Single-cell-width tview box border |
| Pixel-precise spacing | Cell-based proportional spacing |
| Shadow effects | Not reproducible in terminals |
| Rounded corners | Not applicable; square box characters used |
| True-color hex values | Full 24-bit color via tcell on supported terminals |

---

## Testing

```bash
go test ./...           # Run all tests
go test ./... -v        # Verbose output
go vet ./...            # Static analysis
go fmt ./...            # Format check
```

### Test Coverage

| Package | Tests |
|---|---|
| `internal/mock` | Mock state correctness, message visibility |
| `internal/ui/layout` | Margin clamping, message visibility, compact behavior |
| `internal/ui/navigation` | All navigation transitions, stack depth, breadcrumbs |

### Manual Validation Steps

1. Launch both mock states and compare against reference screenshots
2. Navigate all 6 main menu items with ↑/↓ — verify description updates
3. Press Enter on each main menu item — verify submenu appears with correct title
4. Navigate submenu items — verify ↑/↓ work
5. Press Esc from submenu — verify return to main menu with original selection
6. Press Enter on a leaf (submenu item) — verify not-implemented modal appears
7. Press F1 — verify help modal appears
8. Resize terminal live — verify no flickering or corruption
9. Shrink below 60×20 — verify size warning appears

---

## SIXEL Logo Integration POC

The application includes an experimental, isolated proof-of-concept for rendering the official PNG logo using native SIXEL graphics escape sequences:

### Technical Architecture

1. **Embedded Asset:** The official 221×19 px PNG logo is embedded via `//go:embed` inside `internal/ui/sixel`.
2. **SIXEL Encoding:** The asset is converted into DECSIXEL format at startup via `github.com/mattn/go-sixel`, producing a compact 3.9 KB payload.
3. **Screen Buffer Synchronization (`screen.LockRegion`):** During header rendering, the 26-column × 1-row area occupied by the logo is locked in `tcell.Screen`. This guarantees `tcell`'s dirty cell tracking skips those coordinates, preventing the screen engine from overwriting the graphic with background spaces or text on subsequent redraw cycles.
4. **Direct-to-TTY Output:** The SIXEL payload is written directly to the terminal output device (`CONOUT$` on Windows, `/dev/tty` on UNIX) with ANSI cursor save (`\x1b[s`), positioning (`\x1b[%d;%dH`), and restore (`\x1b[u`).
5. **Redraw & Resize Lifecycle:** The logo automatically re-emits when terminal geometry changes (e.g., live window resize) or when modal overlays (such as the F1 Help dialog) are dismissed.
6. **Deadlock Prevention:** `SetFocus()` is strictly avoided inside draw callbacks (`SetBeforeDrawFunc`), ensuring mutex safety during live window resizing.
7. **Graceful Fallback:** Pass `--sixel=false` or resize below minimum width to revert seamlessly to the colored text logo.

---

## Future Integration Boundaries

This prototype establishes the visual foundation. Future phases will:

- Connect to a privileged management daemon via Unix socket or gRPC
- Add real `ApplianceInfo` collection (hostname, IP, uptime) without root
- Implement `System Configuration`, `Network Configuration`, etc. as real forms
- Support product-specific modules (UNFZFS, Tape, Backup) via adapter pattern
- Add authentication gate before main menu on production builds

The TUI must never require root privileges. Privileged operations route through a separate daemon.

---

*Nebara OS TUI — Visual Baseline v0.1 — Prototype only — Mock data only*