# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Company

**OmixLab LTD** - Package namespace: `com.omixlab`

## Git Commit Guidelines

**IMPORTANT**: When creating git commits:
- **DO NOT** add yourself as a co-author (no `Co-Authored-By` lines)
- **Commit messages must be a single line** - keep it concise and descriptive

## Project Overview

Mosis is a **virtual smartphone OS** for VR games and applications. It provides a phone-like device that users can interact with inside VR environments, with real smartphone functionality.

### Current Status

| Component | Status | Notes |
|-----------|--------|-------|
| MosisService | ✅ Working | RmlUi rendering, touch input, navigation |
| App Management | ✅ Working | Install/uninstall apps, sandbox integration |
| Lua Sandbox | ✅ Working | 149 security tests passing |
| Desktop Designer | ✅ Working | Hot-reload, shell mode, hierarchy dump, recording |
| Designer Tests | ✅ 5/5 Passing | Navigation tests automated |
| MosisVR (Unity) | ✅ Building | OpenGL backend working, Vulkan in progress |
| MosisUnreal | ✅ Working | Vulkan texture import via UE5 RHI, phone actor with mesh |

### Project Components

| Component | Location | Purpose |
|-----------|----------|---------|
| Android Service | `src/main/` | Native service running RmlUi renderer |
| App Management | `src/main/cpp/apps/` | App install/uninstall/launch with sandbox |
| Lua Sandbox | `src/main/cpp/sandbox/` | Per-app Lua isolation (22 modules) |
| System Shell | `src/main/assets/apps/shell/` | Persistent status bar, nav bar, overlays |
| Desktop Designer | `designer/` | UI development with hot-reload |
| Designer Tests | `designer-test/` | Automated UI testing framework |
| Sandbox Tests | `sandbox-test/` | Lua sandbox security tests (149 tests) |
| UI Assets | `src/main/assets/` | Shared RML/RCSS/Lua assets |

## Detailed Documentation

All detailed documentation is in `docs/`:

| Document | Description |
|----------|-------------|
| [BUILD-COMMANDS.md](BUILD-COMMANDS.md) | Android, Desktop Designer, and test build commands |
| [ARCHITECTURE.md](ARCHITECTURE.md) | Native libraries, IPC flow, code structure |
| [DESKTOP-DESIGNER.md](DESKTOP-DESIGNER.md) | Shell architecture, hot-reload, recording |
| [TESTING-FRAMEWORK.md](TESTING-FRAMEWORK.md) | Automated UI testing, writing tests |
| [UI-ASSETS.md](UI-ASSETS.md) | Asset structure, navigation system, element IDs |
| [MATERIAL-DESIGN.md](MATERIAL-DESIGN.md) | Icons, MDL components, usage guide |
| [ANDROID-TESTING.md](ANDROID-TESTING.md) | ADB commands, event injection, logs |
| [GAME-ENGINES.md](GAME-ENGINES.md) | Unreal & Unity integration, Vulkan import |
| [DEVELOPER-PORTAL.md](DEVELOPER-PORTAL.md) | Portal architecture, milestones |
| [APP-MANAGEMENT.md](APP-MANAGEMENT.md) | Package format, manifest, lifecycle |
| [LUA-SANDBOX.md](LUA-SANDBOX.md) | Security features, permissions, APIs |

## Quick Reference

### Environment Requirements

- `ANDROID_HOME` - Android SDK path
- `ANDROID_NDK_HOME` - Android NDK path (version 29.0.14206865)
- `VCPKG_ROOT` - vcpkg package manager root

### Common Build Commands

```bash
# Android APK
./gradlew assembleDebug

# Desktop Designer (from designer/)
cmake -B build -DCMAKE_TOOLCHAIN_FILE=%VCPKG_ROOT%/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Debug

# Sandbox Tests (from sandbox-test/)
./run_tests.bat
```

### Code Style

- C++23 standard with modern features (std::span, std::format)
- PascalCase for classes/functions, camelCase for variables
- RAII principles with smart pointers
- Kotlin code follows Android conventions

### Dependencies

- vcpkg: RmlUi, GLFW, Freetype, Lua, libpng, nlohmann-json, minizip, sqlite3
- Android: arm64-v8a only
- Desktop: Windows x64 (MSVC)

## Documentation Guidelines

**IMPORTANT**: Always document progress and new commands to avoid rediscovery.

| Content Type | Location |
|--------------|----------|
| General concepts, architecture | `MosisService/docs/CLAUDE.md` or `docs/` |
| Unreal plugin docs | `MosisUnreal/Plugins/MosisSDK/README.md` |
| Unity package docs | `MosisVR/Packages/com.omixlab.mosis_sdk/README.md` |

**DO NOT** put documentation in the root `D:\Dev\Mosis\` directory - it is not versioned.