Getting started

Your First Screen

A Ketoy screen is a plain @Composable function annotated with

@KetoyComposable and @KetoyEntryPoint. The compiler plugin lowers it to KBC bytecode; the runtime renders it through real Jetpack Compose on the device.

This page walks through writing, building, and viewing a complete "Hello, Ketoy" screen.

1. Create the source file

In your app module, e.g. app/src/main/kotlin/com/example/myapp/ketoyscreens/HelloKetoyScreen.kt:

kotlin

package com.example.myapp.ketoyscreens

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import dev.ketoy.annotations.KetoyComposable
import dev.ketoy.annotations.KetoyEntryPoint

@KetoyComposable
@KetoyEntryPoint
@Composable
fun HelloKetoyScreen() {
    Column(
        modifier = Modifier
            .fillMaxSize()
            .padding(16.dp)
    ) {
        Text(text = "Hello, Ketoy!")
        Spacer(modifier = Modifier.height(8.dp))
        Text(text = "This screen is rendered from a KBC bundle.")
        Spacer(modifier = Modifier.height(24.dp))
        Button(onClick = { /* TODO */ }) {
            Text("Click me")
        }
    }
}

Two annotations matter:

Annotation	What it does
`@KetoyComposable`	Marks this function as a KBC composable. The compiler plugin walks its body, validates every call, and lowers it to bytecode.
`@KetoyEntryPoint`	Registers it as a named entry point in the bundle so the runtime can resolve `entryPoint = "HelloKetoyScreen"`.

Both annotations live in dev.ketoy.annotations.

2. Build the bundle

bash

./gradlew :app:ketoyBundle

Output:

> Task :app:ketoyBundle
KetoyBC: Compilation complete, 7 functions emitted, 1 composables,
0 view models, 1 entry points. Bundle ID: main. Wrote 1542 bytes to
.../app/build/tmp/ketoy_compiler_output/main.ktx (signed)

The KetoyBundleTask then re-signs and copies the bundle to:

app/src/main/assets/ketoy/main.ktx

This file ships inside your APK as an asset. The runtime loads it via KetoyBundleSource.Asset("ketoy/main.ktx").

3. Render it

MainActivity is already wired (from Installation):

kotlin

KetoyScreen(
    bundleSource = KetoyBundleSource.Asset("ketoy/main.ktx"),
    entryPoint = "HelloKetoyScreen",
    nativeFallback = { HelloNativeFallback() }
)

Build & install:

bash

./gradlew :app:installDebug

Launch, you'll see your KBC screen.

4. Iterate

Edit the source. Re-run ./gradlew :app:ketoyBundle. Reinstall. Done.

To verify the bundle's contents without installing:

bash

ketoy analyze app/src/main/assets/ketoy/main.ktx --manifest

Sample output:

Bundle: main (format v2, runtime v1, 1542 bytes signed)
Sections: STRING_POOL, ADAPTER_MANIFEST, CONSTRUCTOR_MANIFEST,
          CAPABILITY_MANIFEST, FUNCTION_TABLE, CODE, ENTRY_POINTS,
          BUNDLE_METADATA
Entry points: HelloKetoyScreen → fn[0]
Composables: 1
ViewModels: 0
Adapters: COLUMN(0x0002), TEXT(0x0001), SPACER(0x000B), BUTTON(0x000C)

What the compiler actually did

Walked HelloKetoyScreen's body via Kotlin IR.
Recognised Column, Text, Spacer, Button against the built-in Material3 adapter catalog.
Resolved 16.dp / 8.dp / 24.dp through the Compose Token Registry, each becomes a single KBCValue.Dp(16f) byte tag in the bundle.
Resolved Modifier.fillMaxSize().padding(16.dp) through the modifier IR walker, the chain is interned into the bundle's modifier table once and referenced by index.
Emitted one COMPOSABLE_CALL opcode per Compose call site with the adapter ID + sparse-encoded parameters.
Wrote everything to the wire format, Brotli-compressed the code section, Ed25519-signed the trailer.

Total size: ~1500 bytes for a screen that, as Kotlin source, takes ~30 lines.

Adding interactivity

Add state with remember { mutableStateOf(...) }:

kotlin

import androidx.compose.runtime.*

@KetoyComposable
@KetoyEntryPoint
@Composable
fun HelloKetoyScreen() {
    var count by remember { mutableStateOf(0) }

    Column(modifier = Modifier.fillMaxSize().padding(16.dp)) {
        Text("Count: $count")
        Button(onClick = { count++ }) {
            Text("Increment")
        }
    }
}

The count++ lambda captures count from the outer scope, Ketoy performs closure conversion at compile time, threading the captured state through KBCValue.ClosureRef at the call site.

For production-grade state that survives rotation, see ViewModel.

Common first-screen mistakes

Symptom	Cause	Fix
`KetoyBC: Direct access to FontWeight.Companion.<get-Bold>`	Token not in seeded registry.	Bold/Medium are seeded, make sure you're on `0.4.16-alpha`.
`KetoyBC: Unregistered composable: com.example.MyWidget`	Calling a `@Composable` that has no adapter.	Either write a custom adapter or wrap it as native UI behind a capability.
`KetoyBC: Direct access to android.util.Log`	Calling `android.*` directly from KBC.	Wrap as a custom capability, or use the built-in `LOG` capability.
Bundle loads but screen is blank	Native fallback rendered instead.	Check `entryPoint` matches the function name exactly. Check `adb logcat \| grep KetoyBundleLoader` for parse/verify errors.

Next: Bundle & Sign for production →