Introduction

Welcome to the KOB3 App SDK documentation. These pages are for app authors building WASI components that run on a KOB3 host.

This book is a stub. Start with What a KOB3 app is and Your first app.

SDK version: 0.1.0 · WIT version: koba:app@0.1.0

What a KOB3 app is

A KOB3 app is a WASI component (.wasm) that runs on a KOB3 host. The host renders your UI on a Screen — a remote display in the household. You do not open a local OS window.

Your app exports lifecycle hooks (start, on_event, pause, resume, stop) and builds a retained UI tree the host displays. See Your first app to walk through the hello template.

Install the App SDK

Download the App SDK zip from /sdk. The kit includes:

• wit/ — the koba:app WIT world
• crates/koba_wasi_sdk/ — capability constants and helpers
• templates/hello/ — a minimal starter app

You need Rust and the wasm32-wasip2 target:

rustup target add wasm32-wasip2

If you want to run apps on real hardware, install KOB3 on a host.

Your first app

The hello template in the SDK zip is the canonical first app. It shows a label and changes the text when you press it.

Each app ships with a manifest.yaml:

id: hello
name: Hello
version: 0.1.0
type: wasm
entry: hello.wasm

Build with cargo build --target wasm32-wasip2 --release from the app directory. The output .wasm plus manifest.yaml is what the host loads.

See the source in the koba repo: apps/hello.

Run it

During development, run your app with the koba harness from a checkout:

koba harness hello

To run on a real host, copy the .wasm and manifest.yaml onto a hosting bundle and install them. See Sideload on a host.

If you do not have a host yet, install KOB3 on a laptop or desktop first.

manifest.yaml

Every KOB3 app includes a manifest.yaml beside its .wasm:

Capabilities are granted by the host based on what your app requests at runtime, not declared in the manifest today. See Sandbox and capabilities.

Lifecycle

Your app implements the guest interface from koba:app:

• start — build the initial UI tree
• on_event — handle inbound events (press, widget activated, …)
• pause / resume — host backgrounded or foregrounded your app
• stop — tear down before the host unloads you

The retained tree is process-local. If the host starts a new process for your app (for example after a crash), rebuild the tree in start.

Sandbox and capabilities

KOB3 apps run in a deny-by-default WASI sandbox. The host grants only the capabilities your app needs: layout, fill, pointer handling, viewports, and so on.

Use constants from koba_wasi_sdk::caps when setting properties on nodes. See Capabilities and the reference.

Retained tree

Build your UI as a retained tree of nodes. Create nodes, set properties, attach children, then commit so the host applies the diff.

#![allow(unused)]
fn main() {
// Pseudocode — see apps/hello for the real pattern
let root = retained::create_node();
retained::set_property(root, caps::LAYOUT, caps::LAYOUT_FLEX_DIRECTION, ...);
retained::append_child(root, label_node);
retained::commit();
}

The host keeps the tree between frames. Mutate it in response to events.

Capabilities

Node properties are keyed by capability and property IDs. Common capabilities:

Import constants from koba_wasi_sdk::caps. Full list: koba_wasi_sdk constants.

Widgets

Widgets are specialized nodes: labels, buttons, text fields, and more. The host maps widget types to platform controls on the Screen.

Handle widget-activated and related events in on_event. The hello app uses a label and responds to press events — start there before adding activation widgets.

Viewports

A viewport is the surface your app draws into:

• Masonry — the default for simple apps; tile-based layout on the Screen
• GPU canvas — advanced; direct GPU drawing (see koba:app gpu interface)

Your first app uses Masonry. Reach for GPU canvas only when you need custom rendering.

WIT koba:app

The composed app world is koba:app@0.1.0 in wit/world.wit.

Interfaces:

Generated HTML reference coming later. Until then, read the WIT source on GitHub.

koba_wasi_sdk constants

The koba_wasi_sdk crate exposes capability and property IDs under caps:

#![allow(unused)]
fn main() {
pub mod caps {
    pub const LAYOUT: u16 = 1;
    pub const FILL: u16 = 2;
    pub const POINTER_HANDLER: u16 = 3;
    pub const VIEWPORT: u16 = 8;
    // ...
}
}

Source: koba_wasi_sdk/src/lib.rs.

Events

Inbound events arrive in on_event via the events interface. Common variants:

See wit/world.wit for the full app-event variant.

Package your app

Ship two files:

1. hello.wasm (or your app name) — release build for wasm32-wasip2
2. manifest.yaml — id, name, version, type: wasm, entry

cargo build --target wasm32-wasip2 --release
cp target/wasm32-wasip2/release/hello.wasm .

Keep the manifest version in sync with your crate version.

Sideload on a host

Copy your .wasm and manifest.yaml onto a KOB3 hosting bundle. The host manager loads WASM apps from its app directory.

You need KOB3 installed on a host first. Lab and checkout installs use koba harness; production sideload paths are documented as the hosting bundle ships.

Catalog and store

Public catalog and store submission are not available yet. Do not expect a submission portal today.

For now, sideload on your own host (Sideload on a host). Store listing will be documented here when koba-store exists.