# 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
```
### 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 `
```
### 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.