Hero OS

A desktop environment framework built with Dioxus (Rust → WASM) that serves as the host for Hero Archipelago islands. Provides macOS-style window management, context switching, and theming for dynamically loaded WASM applications.

Quick Links for AI Assistants

• Backend (Hero0): /Users/timurgordon/code/forge.ourworld.tf/geomind_research/hero0/README.md
• Islands (Hero Archipelagos): /Users/timurgordon/code/forge.ourworld.tf/lhumina_code/hero_archipelagos/README.md
• Architecture Details: ./ARCHITECTURE.md
• Offline Support: ./docs/OFFLINE.md

System Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                          Hero OS (This Project)                             │
│                          Port 8080 (Dioxus dev)                             │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │ Toolbar: [Hero OS ▼]      [App Icon + Views]      [● Context ▼]       │  │
│  ├───────────────────────────────────────────────────────────────────────┤  │
│  │                                                                       │  │
│  │   ┌─────────────────────┐    ┌─────────────────────┐                  │  │
│  │   │ Window: Room Island │    │ Window: Contexts    │                  │  │
│  │   │   <room-island>     │    │ <contexts-island>   │                  │  │
│  │   └─────────────────────┘    └─────────────────────┘                  │  │
│  │                                                                       │  │
│  │   ┌───────────────────────────────────────────────────────────────┐   │  │
│  │   │ Dock: [Room] [Files] [Calendar] [Contexts] ...    [AI Bar]   │   │  │
│  │   └───────────────────────────────────────────────────────────────┘   │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────────┘
         │                                    │
         │ loads WASM islands                 │ islands make API calls
         ▼                                    ▼
┌─────────────────────────┐       ┌─────────────────────────┐
│   Hero Archipelagos     │       │      Hero0 Backend      │
│   Port 8081             │       │      Port 3377 (RPC)    │
│   (Island WASM server)  │       │      Port 3378 (WebDAV) │
└─────────────────────────┘       └─────────────────────────┘

Key Concepts

Contexts

A context is a workspace/namespace that isolates data. Examples: herozero, geomind, my_project.

• Each context has its own desktop state (window positions, open apps)
• Each context can have its own theme (visual appearance)
• Contexts are defined in Hero0 backend at data/mock/root/base/context_*.toml
• The root context is special - it contains metadata about all other contexts

Implementation: On startup, Hero OS fetches all contexts from the root context via the backend API (context.list + context.get). The context selector in the top-right toolbar displays these dynamically fetched contexts.

Themes

A theme defines the visual appearance (colors, typography, spacing). Themes are stored in Hero0 and each context references a theme by name via theme_name field.

How Theming Works:

1. Each Context has an optional theme_name field (e.g., "dark_purple", "dark_pink")
2. On startup and context switch, Hero OS fetches the theme by name from backend
3. Theme properties are converted to CSS custom properties (variables)
4. The UI uses these CSS variables for colors, fonts, spacing

Schema: See geomind_research/hero0/specs/schemas/base/theme.oschema

Theme = {
    sid: sid
    name: str                    # Referenced by Context.theme_name
    mode: "light" | "dark" | "auto"
    colors: ThemeColorPalette    # primary, secondary, background, text, etc.
    typography: ThemeTypography  # font_family, font_size_base, etc.
    spacing: ThemeSpacing        # border_radius, spacing_unit
    is_system: bool
    is_default: bool
}

Available Themes (seeded in data/mock/root/base/):

• dark_purple - Default Hero OS theme with purple accents
• dark_pink - Pink/magenta accents (Geomind context)
• dark_green - Green accents (personal contexts)
• dark_blue - Blue accents (ThreeFold context)
• light - Light theme with blue accents

CSS Variables Applied:

--color-primary, --color-secondary, --color-accent
--color-background, --color-surface, --color-text, --color-text-muted
--color-border, --color-error, --color-warning, --color-success, --color-info
--font-family, --font-family-mono, --font-size-base, --line-height
--border-radius-sm, --border-radius-md, --border-radius-lg, --spacing-unit

Islands

Islands are self-contained WASM applications loaded as web components. Each island:

• Is built with Dioxus and compiled to WASM via wasm-pack
• Registers as a custom HTML element (e.g., <room-island>, <contexts-island>)
• Receives configuration via HTML attributes
• Makes its own API calls to Hero0 backend
• Emits custom DOM events for host communication

Available Islands:

Island	Element	Purpose
room	<room-island>	Video/audio conferencing (LiveKit)
filesystem	<filesystem-island>	File browser (WebDAV)
contexts	<contexts-island>	Workspace management
calendar	<calendar-island>	Event scheduling
contacts	<contacts-island>	Contact management
tasks	<tasks-island>	Task tracking
ai	<ai-island>	AI chat assistant
intelligence	<intelligence-island>	AI agents/roles
settings	<settings-island>	User preferences

Running

All services run through zinit

Both hero_os_server (OpenRPC state backend) and hero_os_ui (HTTP server + RPC proxy) use ZinitLifecycle for process management. There is no standalone/direct mode — all execution goes through zinit.

Prerequisites: zinit_server must be running.

# Binary CLI
hero_os_server run       # start + stream logs + stop on Ctrl-C (developer command)
hero_os_server start     # register + start via zinit (background)
hero_os_server stop      # stop zinit service
hero_os_server status    # query zinit status
hero_os_server logs -n 50
# hero_os_server serve   # internal — zinit calls this, never run manually

Via Make

make run           # start via zinit + stream logs (Ctrl-C stops services)
make start         # start both via zinit (background)
make stop          # stop both zinit services
make status        # show status of both
make logs          # show logs of both

make start and make run both run cargo update first to pick up latest git dependencies before building.

Frontend (Dioxus dev server)

For development with hot reload:

make web           # starts dx serve at http://localhost:8804

Full stack (dev)

# Terminal 0: zinit (if not already running)
zinit_server

# Terminal 1: Backend servers
make run           # starts + streams logs, Ctrl-C stops

# Terminal 2: Frontend with hot reload
make web

Platforms

Hero OS runs on multiple platforms:

Platform	Command	Notes
Web	make web	Default, runs at localhost:8201
iOS	make ios	Requires Xcode, runs in Simulator
Android	make android	Requires Android SDK, runs in emulator
Volla OS	make volla	Builds APK for Volla phones
Desktop	make desktop	Native desktop app

Mobile Builds

Mobile builds use the mobile feature flag with a reduced set of islands optimized for touch interfaces:

• contacts, ai, room, chats, chat_preview, contexts, filesystem

Android/Volla Setup: See docs/ANDROID.md for detailed setup instructions.

Project Structure

hero_os/
├── Cargo.toml
├── Dioxus.toml              # Dioxus configuration
├── README.md                # This file
├── ARCHITECTURE.md          # Detailed architecture docs
│
├── public/
│   ├── islands.js           # Island loader script
│   └── livekit.js           # LiveKit SDK integration
│
└── src/
    ├── main.rs              # App entry, state management
    ├── controller.rs        # Desktop operations (window/context control)
    ├── registry.rs          # Dynamic island registry
    ├── islands.rs           # Island metadata, window state
    ├── storage.rs           # localStorage persistence
    ├── styles.css           # Global styles
    ├── mcp.rs               # MCP tools for AI control
    ├── ai_service.rs        # Groq API integration
    ├── commands.rs          # Command handling
    ├── dom_automation.rs    # DOM manipulation
    │
    └── components/
        ├── mod.rs           # Component exports
        ├── toolbar.rs       # Top toolbar (3 floating islands)
        ├── dock.rs          # Bottom dock (app launcher)
        ├── window.rs        # Window chrome + island rendering
        └── ai_bar.rs        # AI input interface

Key Files to Understand

src/main.rs

• Entry point, initializes the app
• Context list is HARDCODED here - this is a known issue
• Creates DesktopController for window management
• Loads/saves desktop state per context from localStorage

src/components/toolbar.rs

• Top toolbar with 3 floating islands (left, center, right)
• Context dropdown uses hardcoded contexts prop - should fetch from backend
• View tabs for focused window

src/controller.rs

• Unified API for all desktop operations
• switch_context() - save current state, load new context state
• open_window(), close_window(), focus_window(), etc.
• Used by both user actions and AI commands

src/registry.rs

• Dynamically loads island metadata from JavaScript
• Each island's WASM module exports get_metadata() function
• Registry provides icons, views, colors for dock and windows

public/islands.js

• Loads all island WASM modules from Archipelagos server
• Must list every island to load: loadIsland("room"), etc.
• Collects metadata from each island

Data Flow

Context Fetching (Current vs Expected)

Current (Broken):

1. Contexts hardcoded in main.rs as Vec<ContextInfo>
2. Passed to Toolbar component as prop
3. Context selector shows only hardcoded contexts

Expected:

1. On startup, fetch contexts from Hero0: POST /api/root/base/rpc → context.list + context.get
2. Store in signal for reactive updates
3. Both toolbar and contexts app use same data source

Theme Application (To Be Implemented)

Expected Flow:

1. Hero OS loads, queries root context to get all contexts
2. Each context has a theme_sid field referencing a Theme
3. Fetch theme for current context
4. Apply theme colors/typography to CSS variables
5. On context switch, fetch and apply new theme
6. Settings app can change theme → updates context → UI refreshes

API Integration

Islands communicate with Hero0 via JSON-RPC:

POST http://localhost:3377/api/{context}/base/rpc
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "context.list",
  "params": {},
  "id": "1"
}

SDK Usage (in islands):

let client = BaseWasmClient::new("http://localhost:3377", "root");
let sids = client.context_list().await?;
for sid in sids {
    let context = client.context_get(&sid).await?;
}

Adding a New Island

See ARCHITECTURE.md section "Adding a New Island to Hero OS" for detailed steps.

Quick summary:

1. Build island in Hero Archipelagos
2. Add to public/islands.js loader
3. Registry auto-discovers metadata from WASM

Known Issues & TODOs

1. API key exposed: src/ai_service.rs has hardcoded Groq API key - should use environment variable
2. Theme persistence: When user changes theme in settings, it should save to backend via context.set

Related Documentation

Document	Purpose
./ARCHITECTURE.md	Detailed system architecture, island integration
./docs/ANDROID.md	Android/Volla OS setup, building APKs
./docs/MOBILE.md	Mobile-specific sizing, layout, and known issues
./docs/DIOXUS.md	Dioxus configuration, static files, troubleshooting
Hero0 specs/creating-schemas/	Schema design, OSchema syntax
Hero0 docs/SCHEMA_DOCTRINE.md	Schema philosophy
Archipelagos ARCHITECTURE.md	Island structure, SDK usage
Archipelagos docs/VIEW_SYSTEM.md	View definitions, toolbar navigation

Seeding Mock Data

Hero0 uses TOML files for mock data. Contexts are seeded from:

geomind_research/hero0/data/mock/root/base/context_*.toml

Example context:

_type = "Context"
name = "herozero"
title = "HeroZero"
description = "Default HeroZero context"
color = "#8b5cf6"
is_personal = false
is_shared = true

To seed data:

cd geomind_research/hero0
cargo run --bin herozero-seed seed --dir ./data/mock --contexts root,herozero,geomind

For AI Assistants

When working on this codebase:

1. Context selector fix: Modify src/main.rs to fetch contexts from backend on startup. Use the same approach as contexts-island does in context_service.rs.

2. Theme integration:

   • Add theme_sid to Context schema in Hero0
   • Seed theme mock data, get SIDs
   • Update context mock data with theme SIDs
   • Regenerate Hero0 code
   • Fetch and apply themes in Hero OS

3. Testing changes:

   • Backend changes: cd hero0 && cargo build
   • Island changes: cd archipelagos && make build
   • Hero OS changes: dx serve (hot reloads)

4. Common mistakes:

   • Forgetting to rebuild islands after SDK changes
   • Not running the seed command after adding mock data
   • Hardcoding values instead of fetching from backend