ketoy-dev 0.1.0

package/skills/ketoy/reference/forbidden-apis.md

@@ -0,0 +1,149 @@
+# Forbidden APIs in KBC Source
+
+KBC bytecode is **sandboxed**. The compiler plugin rejects entire categories of calls. This is the source of truth for "what can't I do" — every entry here corresponds to a typed diagnostic in `KetoyCompilationError`.
+
+## 1. Direct Android / AndroidX APIs
+
+**Banned**: any FQ starting with `android.` or `androidx.` **outside the registered Compose surface**.
+
+```kotlin
+// ❌ KetoyBC: Direct access to android.widget.Toast.makeText
+Toast.makeText(context, "hi", Toast.LENGTH_SHORT).show()
+
+// ❌ KetoyBC: Direct access to android.content.Context.getSystemService
+val vm = context.getSystemService(VIBRATOR_SERVICE)
+
+// ✅ via capability
+toast("hi")  // stub at 0x0901
+```
+
+The diagnostic includes a fix example pointing at the equivalent capability.
+
+## 2. Reflection
+
+**Banned**: `kotlin.reflect.*`, `java.lang.Class.get*`, `java.lang.reflect.*`.
+
+```kotlin
+// ❌ KetoyBC: Reflection is not allowed in KBC source
+val klass = MyClass::class
+val type = typeOf<MyClass>()
+val fields = obj.javaClass.declaredFields
+
+// ✅ Use sealed classes + when() exhaustive checks
+```
+
+KBC has no class metadata at runtime — reflection literally cannot work. Use sealed classes or enums for type-discriminated logic.
+
+## 3. File I/O
+
+**Banned**: `java.io.*`, `java.nio.*`, `kotlin.io.*` (which wraps `java.io`).
+
+```kotlin
+// ❌ KetoyBC: File I/O is not allowed in KBC source
+File("config.json").readText()
+FileInputStream(path).use { ... }
+
+// ✅ via storage capability
+val raw = kvGet("config_json") as String?
+```
+
+For persistent state use `KV_GET/SET/OBSERVE` (DataStore-backed in the standard library) or `DB_QUERY/OBSERVE` (Room-backed via `KBCRoomBridge`).
+
+## 4. Unstructured concurrency
+
+**Banned**: `GlobalScope`, `runBlocking`, `kotlinx.coroutines.CoroutineScope(...)` factory.
+
+```kotlin
+// ❌ KetoyBC: GlobalScope is forbidden — use viewModelScope
+GlobalScope.launch { fetchData() }
+
+// ❌ KetoyBC: runBlocking is forbidden
+val result = runBlocking { suspendFn() }
+
+// ✅ inside a @KetoyComposable, use LaunchedEffect
+LaunchedEffect(key) {
+    val result = fetchData()  // a @KetoyCapabilityStub suspend fn
+    vmSetState("result", result)
+}
+```
+
+Allowed: `viewModelScope.launch`, `coroutineScope { ... }` builder (structured), `LaunchedEffect`, `withContext(Dispatchers.IO)` (via `WITH_CONTEXT` opcode + dispatcher capabilities).
+
+## 5. Direct construction of non-allowed types
+
+If a constructor isn't in `supported-constructors.md`, the compiler plugin throws `KetoyBC: Direct construction of <type> in KBC source`. The most common culprits:
+
+```kotlin
+// ❌ Brush gradients not on catalog
+Brush.linearGradient(listOf(Color.Red, Color.Blue))
+
+// ❌ Arbitrary data classes (try to construct UiState(...) inside a Composable)
+data class UiState(val name: String)
+UiState("hi")
+```
+
+Fix: pass the value in via state (`vmGetState`) or define an adapter.
+
+## 6. `@Composable` without `@KetoyComposable`
+
+```kotlin
+// ❌ KetoyBC: Unregistered composable com.example.MyHelper
+@Composable
+fun MyHelper() { Text("hi") }
+
+@KetoyComposable
+@Composable
+fun Root() {
+    MyHelper()  // crashes here
+}
+```
+
+**Why**: bare `@Composable` is treated as an external call that needs an adapter (which doesn't exist for arbitrary user code). Either:
+- Add `@KetoyComposable` to the helper (it becomes a KBC function), OR
+- Inline the helper into the calling screen.
+
+This is intentional — Phase 9A tightened detection so `MyHelper` doesn't silently become uncallable.
+
+## 7. Transitive closure errors
+
+Closure validation walks every helper reachable from a `@KetoyComposable` / `@KetoyEntryPoint` / `@KetoyViewModel` root. If a helper does something forbidden, the error carries a breadcrumb:
+
+```
+KetoyBC: Direct access to android.util.Log.d in helper
+  Reached via: TodoListScreen → renderHeader → logHeaderShown
+  ...
+```
+
+**Fix at the leaf**, not the root. The breadcrumb points you there.
+
+**Important**: same-module top-level functions that are NEVER called from a KBC root are **left alone** — they compile to plain DEX. The closure walk only validates code reachable from a KBC root. So you can have native helpers and KBC helpers side-by-side in `:app`.
+
+## 8. Lambda captures (closure conversion)
+
+KBC supports closure conversion for `val`/captured reads, BUT:
+- Captures are snapshotted **eagerly** at the call site. Mutating the parent `val` later does not affect the lambda.
+- Only outer-scope `val`s and parameter reads work. `var` writes from inside a lambda don't propagate.
+- Deeply nested lambdas with many captures slow down compilation. Keep capture sets small.
+
+```kotlin
+// ✅ works — captured outer val
+@KetoyComposable
+fun Screen() {
+    val name = "World"
+    Column {
+        Text("Hello, $name!")  // name captured into the Column content lambda
+    }
+}
+
+// ❌ won't update the outer var
+fun Screen() {
+    var count = 0
+    Button(onClick = { count++ }) { Text("$count") }  // count writes lost
+}
+
+// ✅ use state instead
+fun Screen() {
+    val count = vmGetState("count") as Int? ?: 0
+    Button(onClick = { vmSetState("count", count + 1) }) { Text("$count") }
+}
+```

package/skills/ketoy/reference/supported-composables.md

@@ -0,0 +1,80 @@
+# Supported Composables (as of 0.2.1-alpha)
+
+Every composable callable from KBC source must have a registered adapter. The canonical list is in `ketoy-adapters-material3/src/main/resources/adapter-scan-roots.txt`. Below is the human-readable summary. App-specific adapters live at `0x4000+` registered through a host scan-roots file.
+
+If a composable is **not** in this list, KBC compilation will reject the call with `KetoyBC: Unregistered composable <FQ>`. The fix is one of: (a) it's supported under a different overload — disambiguate; (b) add a custom adapter via `KBCComposableAdapter.register(...)`; (c) keep the screen native.
+
+## Layout & containers
+
+| FQ | Adapter ID | Notes |
+|---|---|---|
+| `androidx.compose.material3.Text` | `0x0001` | String overload, 17 params (post-1.5). AnnotatedString form not supported. |
+| `androidx.compose.foundation.layout.Column` | `0x0002` | |
+| `androidx.compose.foundation.layout.Row` | `0x0003` | |
+| `androidx.compose.foundation.layout.Box` | `0x0004` | |
+| `androidx.compose.foundation.layout.Spacer` | `0x000B` | |
+| `androidx.compose.material3.Scaffold` | `0x0007` | `topBar`, `bottomBar`, `floatingActionButton`, `snackbarHost` content slots all supported. |
+| `androidx.compose.material3.Surface` | `0x0008` | Non-clickable overload (modifier-first). Clickable overload not yet supported. |
+| `androidx.compose.material3.Card` | `0x0009` | 6-param shape/colors/elevation/border form. |
+
+## Lazy lists — NOT supported
+
+`LazyColumn`, `LazyRow` are explicitly deferred (KNOWN_ISSUES #5/#6). The content slot is `LazyListScope.() -> Unit`, a receiver-scoped composable that the KSP codegen doesn't yet handle. **Workaround**: use `Column` with `verticalArrangement` for small lists; for large lists keep the screen native and dispatch through navigation.
+
+## Buttons & interaction
+
+| FQ | Adapter ID | Notes |
+|---|---|---|
+| `androidx.compose.material3.Button` | `0x000C` | |
+| `androidx.compose.material3.IconButton` | `0x000F` | |
+| `androidx.compose.material3.Checkbox` | `0x0014` | |
+| `androidx.compose.material3.Switch` | `0x0016` | |
+
+## Text input
+
+| FQ | Adapter ID | Notes |
+|---|---|---|
+| `androidx.compose.material3.TextField` | `0x0012` | String overload only. AnnotatedString and TextFieldValue not supported. |
+
+## Media
+
+| FQ | Adapter ID | Notes |
+|---|---|---|
+| `androidx.compose.foundation.Image` | `0x0024` | Use `painterResource(R.drawable.X)`; host must register `X` in `MaterialDrawableResolver`. |
+| `coil.compose.AsyncImage` | (see scan-roots) | The painters-and-callbacks overload. |
+| `androidx.compose.material3.Icon` | `0x0019` | Use `Icons.<Style>.<Name>`; host must register the icon in `MaterialIconsResolver`. Material icons-extended required on classpath. |
+
+## TopAppBar family
+
+| FQ | Adapter ID |
+|---|---|
+| `androidx.compose.material3.TopAppBar` | (see scan-roots) |
+
+Note: `TopAppBarDefaults.topAppBarColors(...)` is **constructed** via `CONSTRUCT_JVM`, not called as a composable. See `supported-constructors.md`.
+
+## How to verify a composable is supported
+
+```bash
+grep -i 'YourComposable' /path/to/ketoyvm/ketoy-adapters-material3/src/main/resources/adapter-scan-roots.txt
+```
+
+If grep returns nothing → not supported. Don't invent.
+
+## Adding a custom adapter (app-specific)
+
+Custom composables live in your app's KBC scope at `0x4000+`. Pattern:
+
+```kotlin
+// In your app's Hilt module or App.onCreate:
+KBCComposableAdapter.register(
+    id = 0x4001,
+    fqName = "com.yourapp.ui.MyChart",
+) { p ->
+    MyChart(
+        data = p.getAnyOrNull(0) as List<Float>? ?: emptyList(),
+        modifier = p.getModifier(1),
+    )
+}
+```
+
+Then declare a matching `@KetoyCapabilityStub`-like function in KBC source — or use a custom adapter scan-roots file feeding KSP. See `docs/adapters/custom-composable-adapters.md` in the Ketoy repo for the full flow.

package/skills/ketoy/reference/supported-constructors.md

@@ -0,0 +1,57 @@
+# Supported Constructors (CONSTRUCT_JVM)
+
+When KBC source writes `TextStyle(fontSize = 16.sp, color = Color.White)` or `RoundedCornerShape(40.dp)`, the compiler plugin emits a `CONSTRUCT_JVM` opcode targeting a registered constructor adapter. Only the constructors listed here are supported.
+
+If your KBC code constructs an object whose constructor isn't on this list, you'll get `KetoyBC: Direct construction of <FQ> in KBC source`. The fix is either: (a) use a supported alternative; (b) add a custom `KBCConstructorAdapter` in your host; (c) move the construction host-side and pass via state.
+
+## Built-in constructors
+
+| FQ / Factory | Notes |
+|---|---|
+| `androidx.compose.ui.text.TextStyle` | The full kitchen-sink TextStyle ctor. |
+| `androidx.compose.foundation.text.KeyboardOptions` | |
+| `androidx.compose.foundation.text.KeyboardActions` | |
+| `androidx.compose.foundation.shape.RoundedCornerShape` | Both `(Dp)` and `(Int percent)` forms. |
+| `androidx.compose.ui.text.input.PasswordVisualTransformation` | |
+| `androidx.compose.material3.ButtonDefaults.buttonColors` (factory) | Pass as named args; supported via top-level factory pattern. |
+| `androidx.compose.material3.CardDefaults.cardColors` (factory) | |
+| `androidx.compose.material3.TopAppBarDefaults.topAppBarColors` (factory) | |
+| `androidx.compose.ui.graphics.Color(Long)` | The `Color(0xFFAARRGGBB)` literal form. |
+
+## Atomic-collapse encoder shortcuts
+
+The compiler plugin recognizes these patterns and rewrites them inline — they look like constructor calls in source but don't emit `CONSTRUCT_JVM`:
+
+| Source pattern | Wire encoding | Host resolution |
+|---|---|---|
+| `Color.Red`, `Color.White`, etc. (12 named) | `KBCValue.ColorARGB` literal | inline |
+| `Color(0xFFAARRGGBB)` | `KBCValue.ColorARGB` literal | inline |
+| `16.dp`, `8.dp`, etc. | `KBCValue.Dp(Float)` | inline |
+| `12.sp` | `KBCValue.Sp(Float)` | inline |
+| `FontWeight.Bold`, `.Medium`, etc. (9) | `KBCValue.FontWeightInt` | inline |
+| `FontStyle.Italic` / `.Normal` | `KBCValue.FontStyleId` | inline |
+| `TextAlign.Center` etc. (6) | `KBCValue.TextAlignId` | inline |
+| `TextOverflow.Ellipsis` etc. | `KBCValue.TextOverflowId` | inline |
+| `Arrangement.Center` etc. (12) | `KBCValue.HorizontalArrangementId` / `VerticalArrangementId` | inline |
+| `Alignment.Center` etc. (15) | `KBCValue.HorizontalAlignmentId` / `VerticalAlignmentId` / `ContentAlignmentId` | inline |
+| `ContentScale.Fit` etc. (7) | `KBCValue.ContentScaleId` | inline |
+| `KeyboardType.Password` etc. (8) | `KBCValue.KeyboardTypeId` | inline |
+| `ImeAction.Done` etc. (8) | `KBCValue.ImeActionId` | inline |
+| `FontFamily.Default` / `.SansSerif` / `.Serif` / `.Monospace` / `.Cursive` | `KBCValue.FontFamilyTokenId` | inline |
+| `FontFamily(Font(R.font.X))` | `KBCValue.StringLiteral("X")` | Host `MaterialFontFamilyResolver` |
+| `painterResource(R.drawable.X)` | `KBCValue.StringLiteral("X")` | Host `MaterialDrawableResolver` |
+| `Icons.<Style>.<Name>` | `KBCValue.StringLiteral("Style.Name")` | Host `MaterialIconsResolver` |
+
+## NOT supported
+
+- Arbitrary data class construction (`MyConfig(...)` — define a `KBCComposableAdapter` parameter instead, or pass via state).
+- `Modifier.then(otherModifier)` from outside the supported builder set.
+- `Brush.linearGradient(...)`, `Brush.verticalGradient(...)` — gradient brushes not on the catalog yet.
+- Custom `Shape` implementations.
+- `AnnotatedString.Builder` and `buildAnnotatedString { }`.
+
+## Verifying a constructor is supported
+
+```bash
+grep -i 'YourType' /path/to/ketoyvm/ketoy-adapters-material3/src/main/resources/adapter-scan-roots.txt | grep '^constructor='
+```

package/skills/ketoy/reference/supported-modifiers.md

@@ -0,0 +1,76 @@
+# Supported Modifiers
+
+The `KBCModifierIRWalker` recognizes a fixed set of `Modifier.*` builder calls and encodes them as `KBCModifierOp` entries in the bundle's modifier table. Anything outside this list either passes through as a no-op (rare) or breaks the build with `Unregistered composable <Modifier helper FQ>`.
+
+## Layout
+
+| Builder | Notes |
+|---|---|
+| `Modifier.fillMaxSize()` / `fillMaxSize(fraction)` | |
+| `Modifier.fillMaxWidth()` / `fillMaxWidth(fraction)` | |
+| `Modifier.fillMaxHeight()` / `fillMaxHeight(fraction)` | |
+| `Modifier.size(Dp)` / `size(width = ..., height = ...)` | |
+| `Modifier.width(Dp)` | |
+| `Modifier.height(Dp)` | |
+| `Modifier.padding(Dp)` | All sides |
+| `Modifier.padding(horizontal = ..., vertical = ...)` | |
+| `Modifier.padding(start = ..., top = ..., end = ..., bottom = ...)` | Partial defaults supported (e.g. `padding(top = 24.dp)`) |
+| `Modifier.padding(paddingValues = pv)` | PaddingValues from `Scaffold` content slot — register-passthrough |
+| `Modifier.weight(Float)` | Inside `Row`/`Column` only; layout-scope handled |
+| `Modifier.offset(x = Dp, y = Dp)` | |
+
+## Appearance
+
+| Builder | Notes |
+|---|---|
+| `Modifier.background(color = Color)` | Color must be supported token / `Color(0xFFAARRGGBB)` |
+| `Modifier.background(brush = ...)` | NOT supported (Brush construction outside catalog) |
+| `Modifier.border(width = Dp, color = Color)` | |
+| `Modifier.clip(shape = ...)` | Shape must be `RoundedCornerShape(...)` |
+| `Modifier.alpha(Float)` | |
+| `Modifier.zIndex(Float)` | |
+| `Modifier.aspectRatio(Float)` | |
+
+## Interaction
+
+| Builder | Notes |
+|---|---|
+| `Modifier.clickable { ... }` | Lambda dispatches via VM. No `indication` / `interactionSource` overload. |
+| `Modifier.testTag(String)` | |
+
+## NOT supported
+
+- `Modifier.then(otherModifier)` from outside the catalog.
+- `Modifier.semantics { ... }`.
+- `Modifier.layoutId(...)`, `ConstraintLayout` modifiers.
+- `Modifier.shadow(...)` with elevation Dp — limited support; verify with a tiny test.
+- `Modifier.draw*` modifiers (`drawBehind`, `drawWithContent`).
+- `Modifier.pointerInput(...)` / gesture detectors.
+- Custom `LayoutModifier` implementations.
+
+## Patterns
+
+Chained modifiers with mixed token kinds:
+
+```kotlin
+Modifier
+    .fillMaxWidth()
+    .padding(horizontal = 20.dp, vertical = 12.dp)
+    .clip(shape = RoundedCornerShape(12.dp))
+    .background(color = Color(0xFFEEEEFF))
+```
+
+Partial-default named-arg padding (this works since Phase D of ADR-0001):
+
+```kotlin
+Modifier.padding(top = 48.dp, start = 16.dp, end = 16.dp)  // bottom defaults to 0.dp
+```
+
+Layout-scope `weight`:
+
+```kotlin
+Row(modifier = Modifier.fillMaxWidth()) {
+    Card(modifier = Modifier.weight(3f)) { ... }
+    Card(modifier = Modifier.weight(2f)) { ... }
+}
+```

package/skills/ketoy/templates/app-build.gradle.kts.tmpl

@@ -0,0 +1,109 @@
+// REFERENCE SHAPE — NOT A TARGET TO WRITE WHOLESALE.
+//
+// This is the *final shape* of an `app/build.gradle.kts` after Ketoy
+// integration. Use it as a guide for surgical edits via the safe-edits
+// strategy (skills/ketoy/guides/safe-edits.md). If the user has an
+// existing `app/build.gradle.kts` — and they almost always do — you
+// MUST edit it surgically: insert the plugin, append the dependencies,
+// append the `ketoy { }` block. Overwriting will destroy their existing
+// dependencies, signing config, build types, flavors, ProGuard rules,
+// Crashlytics integration, custom tasks, etc.
+//
+// Only write this file verbatim if the project does not yet have an app
+// module (e.g. fresh `gradle init` skeleton). Even then, you're better
+// off generating the module via Android Studio and editing it surgically.
+//
+// {{PROJECT_NAME}} — placeholders: {{NAMESPACE}}, {{APPLICATION_ID}},
+// {{MIN_SDK}} (>=26), {{TARGET_SDK}}, {{COMPILE_SDK}}, {{VERSION_CODE}},
+// {{VERSION_NAME}}
+
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)
+    // Hilt — keep only if the project uses Hilt:
+    // alias(libs.plugins.ksp)
+    // alias(libs.plugins.hilt)
+    id("dev.ketoy.compiler")
+}
+
+android {
+    namespace = "{{NAMESPACE}}"
+    compileSdk = {{COMPILE_SDK}}
+
+    defaultConfig {
+        applicationId = "{{APPLICATION_ID}}"
+        minSdk = {{MIN_SDK}}            // Ketoy requires API 26+
+        targetSdk = {{TARGET_SDK}}
+        versionCode = {{VERSION_CODE}}
+        versionName = "{{VERSION_NAME}}"
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_17
+        targetCompatibility = JavaVersion.VERSION_17
+    }
+    kotlinOptions {
+        jvmTarget = "17"
+    }
+    buildFeatures {
+        compose = true
+    }
+}
+
+dependencies {
+    // ─── Ketoy ─────────────────────────────────────────────────
+    implementation(platform("dev.ketoy.vm:ketoy-bom:0.2.1-alpha"))
+    implementation("dev.ketoy.vm:ketoy-runtime")
+    implementation("dev.ketoy.vm:ketoy-capabilities-core")
+    implementation("dev.ketoy.vm:ketoy-capabilities-navigation")
+    implementation("dev.ketoy.vm:ketoy-adapters-material3")
+    implementation("dev.ketoy.vm:ketoy-annotations")
+    // For Hilt projects, also:
+    // implementation("dev.ketoy.vm:ketoy-hilt")
+    testImplementation("dev.ketoy.vm:ketoy-test")
+
+    // ─── AndroidX + Compose ──────────────────────────────────────
+    implementation(libs.androidx.core.ktx)
+    implementation(libs.androidx.lifecycle.runtime.ktx)
+    implementation(libs.androidx.activity.compose)
+    implementation(platform(libs.androidx.compose.bom))
+    implementation(libs.androidx.compose.ui)
+    implementation(libs.androidx.compose.material3)
+    // Required if your KBC screens reference Icons.<Style>.<Name>:
+    implementation(libs.androidx.compose.material.icons.extended)
+    implementation(libs.androidx.navigation.compose)
+
+    // ─── DataStore (used by storage capabilities) ───────────────
+    implementation(libs.androidx.datastore.preferences)
+
+    // ─── Coroutines ──────────────────────────────────────────────
+    implementation(libs.kotlinx.coroutines.android)
+}
+
+// ─── KetoyBC compiler plugin configuration ──────────────────────
+//
+// `exportFromAppModule = true` makes the compiler plugin attach to
+// compileReleaseKotlin and emit KBC bytecode only for the transitive
+// call closure rooted in `@KetoyComposable` / `@KetoyEntryPoint` /
+// `@KetoyViewModel` declarations in THIS module. Native code in the
+// same module compiles to DEX as plain Kotlin, untouched.
+//
+// Bundle lands at: app/src/main/assets/ketoy/main.ktx
+ketoy {
+    exportFromAppModule.set(true)
+    bundleId.set("main")
+    bundleVariant.set("release")
+    capabilityRegistryFile.set(file("ketoy-capabilities.json"))
+    debugMode.set(true)
+
+    // Ed25519 raw 32-byte seed for signing. Generate via:
+    //   openssl genpkey -algorithm Ed25519 -outform DER -out key.der
+    //   tail -c 32 key.der > app/keys/sample-private.key
+    // Matching public key at app/src/main/assets/ketoy/keys/sample-public.key.
+    // The private key is .gitignored.
+    val signingKey = file("keys/sample-private.key")
+    if (signingKey.exists()) {
+        signingKeyFile.set(signingKey)
+    }
+}

package/skills/ketoy/templates/ketoy-capabilities.json.tmpl

@@ -0,0 +1,21 @@
+{
+  "version": 1,
+  "allowedStdlibFqNames": [],
+  "capabilities": [
+    { "id": 1792, "name": "NAV_PUSH",
+      "fqName": "{{PACKAGE}}.ketoyscreens.navPush",
+      "kind": "SYNC", "required": true },
+    { "id": 1793, "name": "NAV_POP",
+      "fqName": "{{PACKAGE}}.ketoyscreens.navPop",
+      "kind": "SYNC", "required": true },
+    { "id": 2560, "name": "VM_GET_STATE",
+      "fqName": "{{PACKAGE}}.ketoyscreens.vmGetState",
+      "kind": "SYNC", "required": true },
+    { "id": 2561, "name": "VM_SET_STATE",
+      "fqName": "{{PACKAGE}}.ketoyscreens.vmSetState",
+      "kind": "SYNC", "required": true },
+    { "id": 2562, "name": "VM_OBSERVE_STATE",
+      "fqName": "{{PACKAGE}}.ketoyscreens.vmObserveState",
+      "kind": "FLOW", "required": true }
+  ]
+}

package/skills/ketoy/templates/manifest-snippet.xml.tmpl

@@ -0,0 +1,33 @@
+<!--
+SURGICAL EDIT ONLY: add the `android:name` attribute to the user's EXISTING
+<application> tag. Do NOT replace the whole <application> block — it
+carries android:icon, android:theme, android:label, android:allowBackup,
+possibly tools:replace, network security config, FileProviders, etc.
+
+If the existing <application> already has android:name pointing at a
+non-Ketoy class, stop and ask whether to extend that class or repoint.
+
+For Hilt projects, use the Hilt-aware Application class.
+
+Non-Hilt:
+-->
+<application
+    android:name=".App"
+    android:allowBackup="true"
+    android:icon="@mipmap/ic_launcher"
+    android:label="@string/app_name"
+    android:theme="@style/Theme.{{APP_NAME}}">
+    <!-- ...activities... -->
+</application>
+
+<!--
+Hilt:
+-->
+<application
+    android:name=".MyApplication"
+    android:allowBackup="true"
+    android:icon="@mipmap/ic_launcher"
+    android:label="@string/app_name"
+    android:theme="@style/Theme.{{APP_NAME}}">
+    <!-- ...activities... -->
+</application>

package/templates/HelloKetoyScreen.kt.tmpl

@@ -0,0 +1,51 @@
+package {{PACKAGE}}
+
+import androidx.compose.foundation.layout.Arrangement
+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.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import dev.ketoy.annotations.KetoyComposable
+import dev.ketoy.annotations.KetoyEntryPoint
+
+/**
+ * Default KBC entry-point shipped by `ketoy init`.
+ *
+ * The KetoyBC compiler plugin compiles this function (and every other
+ * `@KetoyComposable` / `@KetoyEntryPoint` reachable from it) into the
+ * `main.ktx` bundle written to `assets/ketoy/main.ktx` at release build
+ * time. At runtime, `KetoyScreen(entryPoint = "HelloKetoyScreen", ...)`
+ * loads + executes it.
+ */
+@KetoyEntryPoint
+@KetoyComposable
+@Composable
+fun HelloKetoyScreen(modifier: Modifier = Modifier) {
+    Column(
+        modifier = Modifier.fillMaxSize().padding(24.dp),
+        verticalArrangement = Arrangement.Center,
+        horizontalAlignment = Alignment.CenterHorizontally,
+    ) {
+        Text(
+            text = "Hello, Ketoy!",
+            fontSize = 28.sp,
+            fontWeight = FontWeight.Bold,
+            color = Color(0xFF4F378B),
+        )
+        Spacer(Modifier.height(8.dp))
+        Text(
+            text = "This screen ships as KBC bytecode inside the APK.",
+            fontSize = 14.sp,
+            color = Color.DarkGray,
+        )
+    }
+}

package/templates/MainActivity.kt.tmpl

@@ -0,0 +1,53 @@
+package {{PACKAGE}}
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.CompositionLocalProvider
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import dev.ketoy.runtime.bundle.KetoyBundleSource
+import dev.ketoy.runtime.compose.KetoyScreen
+import dev.ketoy.runtime.compose.LocalKetoyBundleLoader
+import dev.ketoy.runtime.compose.LocalKetoyRuntime
+
+class MainActivity : ComponentActivity() {
+
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        enableEdgeToEdge()
+        val app = application as MyApplication
+        setContent {
+            MaterialTheme {
+                Surface(modifier = Modifier.fillMaxSize(), color = MaterialTheme.colorScheme.background) {
+                    CompositionLocalProvider(
+                        LocalKetoyRuntime provides app.ketoyRuntime,
+                        LocalKetoyBundleLoader provides app.ketoyBundleLoader,
+                    ) {
+                        KetoyScreen(
+                            entryPoint = "HelloKetoyScreen",
+                            bundleSource = KetoyBundleSource.Asset("ketoy/main.ktx"),
+                        ) {
+                            // Native fallback — rendered when the .ktx bundle is absent,
+                            // incompatible, or corrupt. Replace with your own native screen.
+                            Column(
+                                modifier = Modifier.fillMaxSize(),
+                                verticalArrangement = Arrangement.Center,
+                                horizontalAlignment = Alignment.CenterHorizontally,
+                            ) {
+                                Text("Hello Android")
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}