MosisService/docs/BASE_APPS.md

# Base Apps Migration Plan

Convert system apps from embedded assets to standalone `.mosis` packages in `base-apps/`.

---

## Current State

### Apps in `src/main/assets/apps/`

| App | Files | Icon |
|-----|-------|------|
| home | home.rml, home.lua, lock.rml | home.tga |
| dialer | dialer.rml, calling.rml | phone.tga |
| contacts | contacts.rml | contacts.tga |
| messages | messages.rml | message.tga |
| settings | settings.rml | settings.tga |
| browser | browser.rml | browser.tga |
| camera | camera.rml | camera.tga |
| store | store.rml | store.tga |
| music | music.rml | music.tga |

### Shared Dependencies

All apps currently reference shared resources via relative paths:

```
../../ui/html.rcss      - Base HTML element styles
../../ui/theme.rcss     - Color scheme, typography
../../ui/components.rcss - Buttons, cards, lists
../../scripts/navigation.lua - Screen navigation system
../../icons/*.tga       - App and UI icons
```

### Current Navigation Model

Apps are not truly separate - they're screens loaded via a central navigation system:

```lua
-- navigation.lua
local screens = {
    home = "apps/home/home.rml",
    dialer = "apps/dialer/dialer.rml",
    -- etc.
}
mosis.loadDocument(screens[name])
```

---

## Target State

### Directory Structure

```
base-apps/
├── com.mosis.home/
│   ├── manifest.json
│   ├── main.rml
│   ├── home.lua
│   ├── lock.rml
│   ├── icon.tga
│   └── styles.rcss
├── com.mosis.dialer/
│   ├── manifest.json
│   ├── main.rml (dialer.rml)
│   ├── calling.rml
│   ├── icon.tga
│   └── styles.rcss
├── com.mosis.contacts/
├── com.mosis.messages/
├── com.mosis.settings/
├── com.mosis.browser/
├── com.mosis.camera/
├── com.mosis.store/
├── com.mosis.music/
└── package.bat
```

### Package IDs

| App | Package ID |
|-----|------------|
| Home | com.mosis.home |
| Dialer | com.mosis.dialer |
| Contacts | com.mosis.contacts |
| Messages | com.mosis.messages |
| Settings | com.mosis.settings |
| Browser | com.mosis.browser |
| Camera | com.mosis.camera |
| Store | com.mosis.store |
| Music | com.mosis.music |

---

## Key Decisions

### 1. Shared Resources Strategy

**Decision**: System asset path (`/system/`)

Apps reference shared resources via a system path that the kernel provides:

```html
<link type="text/rcss" href="/system/ui/theme.rcss"/>
<script src="/system/scripts/navigation.lua"></script>
```

The kernel maps `/system/` to `src/main/assets/` (or bundled assets on Android).

**Rationale**:
- Avoids duplicating ~50KB of styles/icons per app
- Single source of truth for theming
- Apps can still have local overrides

### 2. Navigation Model

**Decision**: Hybrid approach

- **System apps** (home, dialer, contacts, etc.) use shared navigation for seamless transitions
- **Third-party apps** launch via `mosis.apps.launch()` with isolated sandbox

System apps get `is_system_app = true` flag:
- Can access `/system/` resources
- Share navigation state
- Can load each other's screens directly

### 3. Home App Special Status

The home app is the launcher/shell:
- Always running in background
- Provides dock and app grid
- Launches other apps via `mosis.apps.launch(package_id)`
- Cannot be uninstalled

---

## Implementation Tasks

### Phase 1: Infrastructure

- [ ] **1.1** Rename `test-apps/` to `base-apps/`
- [ ] **1.2** Move `com.mosis.sandbox-test` to `base-apps/`
- [ ] **1.3** Implement `/system/` path mapping in kernel
  - Desktop: Map to `assets/` directory
  - Android: Map to bundled assets
- [ ] **1.4** Add `is_system_app` flag to manifest schema
- [ ] **1.5** Update designer `--test-apps` flag to `--apps` for consistency

### Phase 2: Convert Apps

For each app:

- [ ] **2.1** Create package directory in `base-apps/com.mosis.{name}/`
- [ ] **2.2** Create `manifest.json` with proper metadata
- [ ] **2.3** Copy RML files, rename entry to `main.rml`
- [ ] **2.4** Copy app-specific Lua scripts
- [ ] **2.5** Copy icon from `icons/{name}.tga` to `icon.tga`
- [ ] **2.6** Update resource paths to use `/system/` prefix
- [ ] **2.7** Create `styles.rcss` for app-specific styles (extract from inline)

### Phase 3: Update Home App

- [ ] **3.1** Update home.lua to use `mosis.apps.launch()` for launching
- [ ] **3.2** Keep shared navigation for system app transitions
- [ ] **3.3** Display all installed apps (base + third-party) in grid
- [ ] **3.4** Update dock icons to launch via package ID

### Phase 4: Cleanup

- [ ] **4.1** Remove old `src/main/assets/apps/` directory
- [ ] **4.2** Update build scripts to package base-apps
- [ ] **4.3** Update Android to include base-apps packages
- [ ] **4.4** Update documentation

---

## Manifest Examples

### System App (Dialer)

```json
{
  "id": "com.mosis.dialer",
  "name": "Phone",
  "version": "1.0.0",
  "version_code": 1,
  "entry": "main.rml",
  "icon": "icon.tga",
  "description": "Make and receive phone calls",
  "developer": {
    "name": "Mosis Team",
    "email": "dev@mosis.dev"
  },
  "permissions": [
    "contacts.read"
  ],
  "is_system_app": true,
  "min_api_version": 1
}
```

### Home App (Launcher)

```json
{
  "id": "com.mosis.home",
  "name": "Home",
  "version": "1.0.0",
  "version_code": 1,
  "entry": "main.rml",
  "icon": "icon.tga",
  "description": "Mosis Home Launcher",
  "developer": {
    "name": "Mosis Team",
    "email": "dev@mosis.dev"
  },
  "permissions": [
    "system.launcher"
  ],
  "is_system_app": true,
  "is_launcher": true,
  "min_api_version": 1
}
```

---

## Resource Path Mapping

### Before (Relative)

```html
<link type="text/rcss" href="../../ui/theme.rcss"/>
<script src="../../scripts/navigation.lua"></script>
<img src="../../icons/phone.tga"/>
```

### After (System Path)

```html
<link type="text/rcss" href="/system/ui/theme.rcss"/>
<script src="/system/scripts/navigation.lua"></script>
<img src="/system/icons/phone.tga"/>
```

---

## Testing Checklist

- [ ] Designer loads home from `base-apps/com.mosis.home/`
- [ ] All base apps appear in home screen grid
- [ ] Tapping app icon launches the app
- [ ] Navigation between system apps works (back button, dock)
- [ ] Third-party apps (sandbox-test) launch in isolated sandbox
- [ ] `/system/` paths resolve correctly
- [ ] Android build includes all base-apps packages
- [ ] Hot-reload still works for development

---

## Open Questions

1. **Lock screen**: Part of home app or separate `com.mosis.lockscreen`?
2. **Calling screen**: Part of dialer or system-level overlay?
3. **Notifications**: System-level or per-app handling?
4. **Settings persistence**: Shared settings service or per-app?

---

## File Changes Summary

| Action | Path |
|--------|------|
| Rename | `test-apps/` → `base-apps/` |
| Create | `base-apps/com.mosis.{home,dialer,...}/` |
| Create | Each app's `manifest.json` |
| Move | App RML/Lua files to package dirs |
| Update | RML paths from `../../` to `/system/` |
| Delete | `src/main/assets/apps/` (after migration) |
| Update | Designer command line args |
| Update | Android asset bundling |

---

## Reusable Layout Components

New standardized UI components for consistent app layouts. Located in `src/main/assets/ui/layout.rcss` and `src/main/assets/scripts/layout.lua`.

### Components

| Component | CSS Class | Description |
|-----------|-----------|-------------|
| Status Bar | `.system-status-bar` | Top bar with time, wifi, signal, battery |
| App Bar | `.app-bar` | Title bar with back button and actions |
| System Nav | `.system-nav-bar` | Bottom bar with back, home, recent buttons |
| App Screen | `.app-screen` | Standard app screen container |
| App Content | `.app-content` | Scrollable content area |

### Standard App Structure

```html
<body class="app-screen" onload="initLayout(document)">
    <!-- System Status Bar -->
    <div class="system-status-bar">
        <span id="status-time" class="system-status-time">12:30</span>
        <div class="system-status-icons">
            <img src="../../icons/wifi.tga"/>
            <img src="../../icons/signal.tga"/>
            <img src="../../icons/battery.tga"/>
        </div>
    </div>

    <!-- App Bar -->
    <div class="app-bar">
        <div class="app-bar-back" onclick="goBack()">
            <img src="../../icons/back.tga"/>
        </div>
        <span class="app-bar-title">App Title</span>
        <div class="app-bar-actions">
            <div class="app-bar-action">
                <img src="../../icons/search.tga"/>
            </div>
        </div>
    </div>

    <!-- Content Area -->
    <div class="app-content with-nav">
        <!-- App content here -->
    </div>

    <!-- System Navigation Bar -->
    <div class="system-nav-bar">
        <div class="system-nav-btn" onclick="onBackPressed()">
            <img src="../../icons/back.tga"/>
        </div>
        <div class="system-nav-home" onclick="onHomePressed()"></div>
        <div class="system-nav-btn" onclick="onRecentPressed()">
            <img src="../../icons/menu.tga"/>
        </div>
    </div>
</body>
```

### Required Includes

```html
<head>
    <link type="text/rcss" href="../../ui/html.rcss"/>
    <link type="text/rcss" href="../../ui/theme.rcss"/>
    <link type="text/rcss" href="../../ui/components.rcss"/>
    <link type="text/rcss" href="../../ui/layout.rcss"/>
    <script src="../../scripts/navigation.lua"></script>
    <script src="../../scripts/layout.lua"></script>
</head>
```

### CSS Modifiers

| Class | Description |
|-------|-------------|
| `.app-content.with-nav` | Adds bottom padding for system nav bar |
| `.app-content.with-dock` | Adds bottom padding for dock |
| `.app-bar.transparent` | Transparent app bar background |
| `.system-status-bar.bg-surface` | Solid surface color background |

### Lua Functions (layout.lua)

| Function | Description |
|----------|-------------|
| `initLayout(doc)` | Initialize all layout components |
| `initStatusBar(doc)` | Setup status bar time updates |
| `onBackPressed()` | Handle back button (goes back or home) |
| `onHomePressed()` | Handle home button |
| `onRecentPressed()` | Handle recent apps button |

### Updated Apps

- [x] Settings - Uses full layout with system nav bar
- [x] Contacts - Uses status bar and app bar (has own bottom tabs)
- [ ] Other apps - Still using old structure

---

*Created: 2025-01-19*
*Updated: 2025-01-20*