MosisService/docs/DESKTOP-DESIGNER.md

# Desktop Designer

The desktop designer (`designer/`) provides rapid UI development with:

- **Hot-reload**: Automatically reloads when RML/RCSS/Lua files change
- **Shell Mode**: Persistent system UI (status bar, nav bar) with apps loading into container
- **UI Hierarchy Dumping**: Exports element tree to JSON for inspection
- **Screenshot Capture**: PNG export via F12 key
- **Logging**: Detailed output for debugging navigation and events
- **Action Recording**: Record mouse/keyboard interactions to JSON
- **Action Playback**: Replay recorded interactions with timing

## Key Files

| File | Purpose |
|------|---------|
| `designer/main.cpp` | Main entry point, GLFW window, event loop |
| `designer/src/desktop_sandbox.cpp` | Per-app sandbox isolation |
| `designer/src/app_discovery.cpp` | Scans directories for app manifests |
| `designer/src/testing/ui_inspector.cpp` | UI hierarchy JSON export |
| `designer/src/testing/visual_capture.cpp` | PNG screenshot capture |
| `designer/src/testing/action_recorder.cpp` | Record user interactions |
| `designer/src/testing/action_player.cpp` | Playback recorded actions |

## Command Line Options

```
General:
  --resolution WxH    Set window resolution (default: 540x960)
  --assets PATH       Set assets directory (default: derived from document)
  --log FILE          Write all log messages to file
  --hierarchy FILE    Continuously dump UI hierarchy to JSON

Simulator mode:
  --simulator         Run in simulator mode (uses shell by default)
  --no-shell          Disable shell (use direct document loading)
  --test-apps PATH    Path to test-apps directory (default: ./base-apps)

Test modes:
  --record FILE       Record user actions to JSON file
  --playback FILE     Playback actions from JSON file
  --screenshot FILE   Take screenshot and exit
  --dump-hierarchy FILE  Dump UI hierarchy to JSON and exit
```

## Running the Designer

### Simulator Mode with Shell (Recommended)

```bash
cd MosisService
./designer/build/Release/mosis-designer.exe --simulator --test-apps base-apps
```

This will:
- Load the **system shell** with persistent status bar and navigation bar
- Load home screen content into the shell's app container
- Scan `base-apps/` for apps with valid `manifest.json`
- Enable app navigation with proper back button support

### Simulator Mode without Shell

To test the old direct-document approach:

```bash
./designer/build/Release/mosis-designer.exe --simulator --test-apps base-apps --no-shell
```

### Direct Document Mode

To load a specific RML document directly:

```bash
./designer/build/Release/mosis-designer.exe path/to/document.rml
```

## Keyboard Controls

| Key | Function |
|-----|----------|
| F5 | Reload document / Start-stop recording |
| F12 | Toggle RmlUi debugger |
| ESC | Back navigation |
| R | Start/Stop recording (in interactive mode) |

---

## Shell Architecture

The shell (`apps/shell/`) provides a persistent system UI layer that prevents apps from taking over the full screen.

### Shell Components

```
┌──────────────────────────────┐
│     Status Bar (36px)        │  ← Time, WiFi, Signal, Battery
├──────────────────────────────┤
│                              │
│     App Container            │  ← App content loads here
│     (flex: 1)                │
│                              │
├──────────────────────────────┤
│     Navigation Bar (56px)    │  ← Back, Home, Recents
└──────────────────────────────┘

Overlay Layers (z-index order):
- Dialog overlay (z: 600)      ← Modal dialogs
- Toast container (z: 500)     ← Toast notifications
- Notification panel (z: 400)  ← Pull-down notifications
- Loading overlay (z: 300)     ← App loading spinner
```

### Shell Files

| File | Purpose |
|------|---------|
| `apps/shell/shell.rml` | Shell document with status bar, nav bar, overlays |
| `apps/shell/shell.lua` | Navigation, toasts, dialogs, notifications |

### App Content Fragments

Apps in shell mode use **content fragments** (`*_content.rml`) instead of full documents:

```rml
<!-- camera_content.rml - No <rml>, <head>, or document structure -->
<style>
    .camera-content { ... }
</style>

<div class="camera-content">
    <!-- App UI here -->
</div>
```

### Shell Lua API

Functions available to apps via shell:

```lua
-- Navigation
shellNavigateTo("settings")      -- Navigate to system app
shellLaunchApp(id, path, entry)  -- Launch external app
shellGoBack()                    -- Go to previous app
shellGoHome()                    -- Go to home (clear history)

-- UI Feedback
showToast("Message")             -- Show toast notification
showToast("Error!", "error")     -- Toast types: default, success, error, warning
showDialog("Title", "Message", onConfirm, onCancel)

-- Notifications
addNotification("Title", "Text", icon, app_id)
toggleNotifications()            -- Show/hide notification panel
clearNotifications()
```

### Creating Content Fragments

1. Create `appname_content.rml` (not a full document)
2. Include styles via `<style>` tag
3. Use shell functions for navigation (`shellNavigateTo`, `showToast`, etc.)
4. Don't include status bar or nav bar (shell provides these)

Example:
```rml
<!-- settings_content.rml -->
<style>
    .settings-list { padding: 16px; }
    .settings-item { padding: 16px; cursor: pointer; }
</style>

<div class="settings-list">
    <div class="settings-item" onclick="showToast('WiFi settings')">
        WiFi
    </div>
    <div class="settings-item" onclick="showToast('Bluetooth settings')">
        Bluetooth
    </div>
</div>
```

### Content Fragment Locations

| App | Content Fragment Path |
|-----|----------------------|
| Home | `apps/home/home_content.rml` |
| Camera | `apps/camera/camera_content.rml` |
| Dialer | `apps/dialer/dialer_content.rml` |
| Messages | `apps/messages/messages_content.rml` |
| Browser | `apps/browser/browser_content.rml` |
| Settings | `apps/settings/settings_content.rml` |
| Music | `apps/music/music_content.rml` |
| Store | `apps/store/store_content.rml` |
| Contacts | `apps/contacts/contacts_content.rml` |

---

## Hot Reload

The designer watches for file changes in the assets directory:

- **RML files**: Reloads document
- **RCSS files**: Reloads stylesheets
- **Lua files**: Reloads scripts
- **TGA/PNG files**: Reloads textures

Press F5 to force reload.

## UI Hierarchy Dump

Use `--hierarchy` to continuously dump the UI element tree:

```bash
./designer/build/Release/mosis-designer.exe --simulator --hierarchy ui_tree.json
```

The JSON contains element bounds, classes, IDs, and visibility - useful for automated testing.

## Action Recording and Playback

See [TESTING-FRAMEWORK.md](TESTING-FRAMEWORK.md) for details on recording and playing back UI interactions.