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:

-- 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:

<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)

{
  "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)

{
  "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)

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

After (System Path)

<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

<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

<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

• Settings - Uses full layout with system nav bar
• 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