Hero Archipelagos

Self-contained Dioxus WASM island applications that connect to Hero0 via the herozero-sdk.

Core Principles

ALL ISLANDS ARE:

1. Dioxus applications - Built with Dioxus 0.7 for Rust-based reactive UI
2. WASM modules - Compiled to WebAssembly, run in the browser
3. herozero-sdk consumers - Use the WASM SDK client to communicate with Hero0
4. Web Components - Registered as custom HTML elements with Shadow DOM isolation (standalone mode)
5. Embeddable - Can be imported as library components into host applications (embedded mode)

NO Python servers. NO Node.js. Pure Rust + WASM.

Build Modes

Islands support two build modes via the standalone feature:

Standalone Mode (default)

Each island builds as a separate WASM module with web component registration.

• Total size: ~6.4 MB brotli (all 9 islands + Hero OS)
• Use case: Dynamic loading, independent deployment

Embedded Mode

Islands compile as library components without web component exports, sharing a single Dioxus runtime.

• Total size: ~1.1 MB brotli (Hero OS with all 9 islands embedded)
• Savings: 83% size reduction
• Use case: Unified builds, smaller total footprint

See docs/WASM_OPTIMIZATION.md for details.

Quick Start

Prerequisites

# Install wasm-pack
cargo install wasm-pack

# Rust 1.85+
rustup update stable

Build and Run

# Build all islands and start the Rust server
make dev

# Or step by step:
make build    # Build all WASM islands
make serve    # Start Rust server on port 8081

Using an Island (Standalone Mode)

<!-- Load the island -->
<script type="module">
  import init from 'http://localhost:8081/islands/room/pkg/hero_archipelagos_room.js';
  await init();
</script>

<!-- Use the Web Component -->
<room-island
  backend-url="http://localhost:3377"
  context-name="herozero"
  user-name="Alice">
</room-island>

Embedding Islands (Embedded Mode)

# Cargo.toml - disable standalone feature
[dependencies]
hero_archipelagos_filesystem = { path = "path/to/islands/filesystem", default-features = false }

use hero_archipelagos_filesystem::app::FilesystemIslandApp;
use hero_archipelagos_shared::IslandContext;

#[component]
fn MyApp() -> Element {
    let context = IslandContext::default();
    rsx! {
        FilesystemIslandApp {
            context: context,
            initial_path: "/".to_string(),
        }
    }
}

Available Islands

Island	Element	Description	SDK Features
Room	<room-island>	Video/audio conferencing	communication
Filesystem	<filesystem-island>	File browser (WebDAV)	N/A (raw fetch)
Contexts	<contexts-island>	Workspace management	base
Calendar	<calendar-island>	Event management	calendar
Contacts	<contacts-island>	Contact management	identity
Tasks	<tasks-island>	Task management	projects
Intelligence	<intelligence-island>	AI agents/roles/knowledge	ai, embedder
Settings	<settings-island>	System settings	base
AI	<ai-island>	AI chat assistant	ai

Project Structure

hero_archipelagos/
├── Cargo.toml              # Workspace definition
├── Makefile                # Build commands
├── ARCHITECTURE.md         # Technical documentation
│
├── shared/                 # Shared library for all islands
│   └── src/
│       ├── context.rs      # IslandContext (from HTML attributes)
│       ├── events.rs       # Custom event emission
│       └── web_component.rs # Custom element registration
│
├── islands/                # WASM island applications
│   ├── room/              # Dioxus + herozero-sdk[communication]
│   ├── filesystem/        # Dioxus + WebDAV
│   ├── contexts/          # Dioxus + herozero-sdk[base]
│   ├── calendar/          # Dioxus + herozero-sdk[calendar]
│   ├── contacts/          # Dioxus + herozero-sdk[identity]
│   ├── tasks/             # Dioxus + herozero-sdk[projects]
│   ├── intelligence/      # Dioxus + herozero-sdk[ai, embedder]
│   ├── settings/          # Dioxus + herozero-sdk[base]
│   └── ai/                # Dioxus + herozero-sdk[ai]
│
├── docs/                   # Documentation
│   ├── WASM_OPTIMIZATION.md  # Size optimization & build modes
│   ├── VIEW_SYSTEM.md        # View/tab system
│   └── THEMING.md            # Theming guide
│
└── server/                 # Rust static file server (axum)
    └── src/main.rs         # Serves islands with CORS + gzip

Building Islands

# Build all islands (standalone mode)
make build

# Build single island
make room
make calendar
make contacts
make tasks
make ai

# Build for production (optimized)
make release

# Check sizes
make sizes

Development Server

The Rust server at server/ serves the built islands:

# Start server on default port 8081
make serve

# Custom port
PORT=9000 make serve

Features:

• CORS enabled for cross-origin requests
• Gzip compression for WASM files
• Static file serving from islands/*/pkg/

Island Development

Creating a New Island

1. Create the directory structure:

mkdir -p islands/myisland/src/{services,views}

2. Create Cargo.toml:

[package]
name = "hero_archipelagos_myisland"
version.workspace = true
edition.workspace = true

[lib]
crate-type = ["cdylib", "rlib"]

[features]
default = ["standalone"]
standalone = []

[dependencies]
hero_archipelagos_shared = { path = "../../shared" }
dioxus.workspace = true
wasm-bindgen.workspace = true
herozero-sdk = { workspace = true, features = ["mydomain"] }
# ... other deps

3. Create src/lib.rs with Web Component registration (wrapped in #[cfg(feature = "standalone")])
4. Create src/app.rs with Dioxus app (always available for embedding)
5. Create src/services/ for SDK client calls
6. Add to workspace Cargo.toml
7. Add to Makefile

See ARCHITECTURE.md for detailed documentation.

Context Attributes

Attribute	Required	Description
backend-url	Yes	Hero0 RPC server URL (port 3377)
webdav-url	No	Hero0 WebDAV server URL (port 3378)
context-name	Yes	Namespace identifier
user-name	No	Display name
theme	No	Theme: dark or light
view	No	Initial view to display

SDK Integration

Each island uses the herozero-sdk WASM client:

// In Cargo.toml
herozero-sdk = { workspace = true, features = ["calendar"] }

// In your service
use herozero_sdk::calendar::CalendarWasmClient;

pub async fn fetch_events(backend_url: &str, context: &str) -> Result<Vec<Event>, String> {
    let client = CalendarWasmClient::new(backend_url, context);
    client.event_list().await
}

License

Apache-2.0