I lost days to this. The Android emulator would launch, show the boot animation, and just sit there. No error dialog in Android Studio, no crash popup, nothing. An infinite boot loop with zero indication of what went wrong.

If you have an AMD GPU on Linux with AMDVLK installed, this post should save you some time.

The problem

I’m working on an Android project with an emulator image (android-34, x86_64). AMD Ryzen + AMD Radeon RX (RDNA 3), Ubuntu. The emulator process starts fine. QEMU runs, ADB connects, boot animation plays. But sys.boot_completed never becomes 1. The system hangs mid-boot and never recovers.

Android Studio tells you nothing. I tried cold boots, wiping data, recreating the AVD, different API levels. None of it mattered.

Finding the root cause

I ended up working through this with Claude Code, which got me past the guessing stage and into the system logs. Took maybe 15 minutes once we stopped flailing.

Confirm the boot is stuck

adb shell getprop sys.boot_completed
# (empty)

adb shell getprop init.svc.bootanim
# running

Empty sys.boot_completed and a still-running boot animation. System is alive but stuck.

Check logcat

adb logcat -d | grep -i -E 'fatal|crash|vulkan'

This surfaced the problem immediately:

Vulkan Instance Version: 1.3.0
Device AMD Radeon RX XXXX, API Version 1.3.0, Driver Version 2.0.349
Failed to find appropriate memory type for 10 with properties 6!

The Vulkan compositor crashed during init. It couldn’t find a memory type it needed.

Check the crash buffer

adb logcat -d -b crash

Full crash trace:

signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr 0x0
Cause: null pointer dereference
Cmdline: /system/bin/surfaceflinger

backtrace:
  #00 libvulkan_compositor.so (GraphicsObject::GetVkDevice() const+0)
  #01 libvulkan_compositor.so (LayerTextureCache::Initialize()+1563)
  #02 libvulkan_compositor.so (compositor::CreateDevice()+864)
  #03 surfaceflinger (VulkanRendererDevice::init()+2284)

Followed by:

init: process 'surfaceflinger' exited 4 times before boot completed

Vulkan memory allocation fails, VkDevice comes back null, null pointer dereference, surfaceflinger crashes. Init restarts it, same crash, four times, init gives up. Boot hangs forever.

Root cause

The Android emulator uses gfxstream to translate Vulkan calls from the guest to your host GPU. It maps guest Vulkan memory types to host memory types.

AMDVLK (AMD’s official Vulkan driver) exposes AMD-specific memory property flags through the VK_AMD_device_coherent_memory extension:

# AMDVLK: 16 memory types, including non-standard ones
Type 0:  DEVICE_LOCAL                                     (0x0001)
Type 1:  HOST_VISIBLE | HOST_COHERENT                     (0x0006)
Type 2:  DEVICE_LOCAL | HOST_VISIBLE | HOST_COHERENT      (0x0007)
Type 3:  HOST_VISIBLE | HOST_COHERENT | HOST_CACHED       (0x000e)
Type 4:  DEVICE_LOCAL | DEVICE_COHERENT_AMD | DEVICE_UNCACHED_AMD  (0x00c1)  <-- non-standard
Type 5:  HOST_VISIBLE | HOST_COHERENT | DEVICE_COHERENT_AMD | ...  (0x00c6)  <-- non-standard
...

DEVICE_COHERENT_BIT_AMD and DEVICE_UNCACHED_BIT_AMD are not part of the core Vulkan spec. gfxstream doesn’t know what to do with them. The compositor asks for HOST_VISIBLE | HOST_COHERENT memory, gfxstream chokes on the extra AMD flags, the lookup fails.

I verified this by reading the gfxstream source. The bug is a missing filter at three points:

In vk_emulated_physical_device_memory.cpp, host memory properties are copied to the guest verbatim:

mHostMemoryProperties = hostMemoryProperties;
mGuestMemoryProperties = hostMemoryProperties;  // AMD flags included, no filtering

Later, when gfxstream strips HOST_COHERENT_BIT for certain configurations, it only strips the standard flag (0x4) and leaves the AMD-specific DEVICE_COHERENT_BIT_AMD (0x40) intact. The guest ends up with an inconsistent set of memory flags.

In vk_decoder_global_state.cpp, the extension filter list (kEmulatedDeviceExtensions) only blocks Android/Fuchsia/external-memory extensions. VK_AMD_device_coherent_memory is not in the list, so the guest thinks the extension is available and expects the non-standard memory types to work through gfxstream. They don’t.

And in transformToGuestMemoryRequirements(), the memoryTypeBits are remapped by index but the property flags are never masked. AMD-specific flags pass straight through to the guest compositor, which has no idea what to do with them.

gfxstream should either strip AMD-specific memory property flags from guest memory types, or filter the VK_AMD_device_coherent_memory extension from the device extension list. It does neither.

RADV (Mesa’s Vulkan driver for AMD) doesn’t have this problem because it only exposes standard Vulkan memory types:

# RADV: 11 memory types, all standard
Type 0:  DEVICE_LOCAL                                (0x0001)
Type 1:  DEVICE_LOCAL                                (0x0001)
Type 2:  HOST_VISIBLE | HOST_COHERENT                (0x0006)
Type 3:  DEVICE_LOCAL | HOST_VISIBLE | HOST_COHERENT (0x0007)
Type 4:  DEVICE_LOCAL | HOST_VISIBLE | HOST_COHERENT (0x0007)
Type 5:  HOST_VISIBLE | HOST_COHERENT | HOST_CACHED  (0x000e)
...

No vendor extensions, no confusion, gfxstream maps everything correctly.

The fix

Just remove AMDVLK:

sudo apt remove amdvlk

That’s it. RADV (which ships with Mesa and is already installed on most Linux distros) becomes the only Vulkan driver. No environment variables, no per-app overrides, no profile files to worry about. Restart Android Studio and the emulator boots.

Verify:

vulkaninfo --summary 2>&1 | grep driverName
# Should show: radv

I initially tried a softer fix, setting VK_ICD_FILENAMES to force RADV while keeping AMDVLK installed. That works too, but it’s fiddly. You have to put it in ~/.profile (not ~/.bashrc) because GUI apps like Android Studio don’t source bash configs. And you have to remember to override it back if you ever want AMDVLK for something. Removing the package is simpler and I haven’t missed it.

Quick check: are you affected?

# Is AMDVLK installed?
dpkg -l | grep amdvlk

# Which driver is active?
vulkaninfo --summary 2>&1 | grep driverName
# "AMD open-source driver" = AMDVLK (problematic)
# "radv" = RADV (works)

# Do you have non-standard memory types?
vulkaninfo 2>&1 | grep DEVICE_COHERENT
# If this returns anything, AMDVLK is active

AMDVLK vs RADV

AMD is replacing AMDVLK with RADV as their official Vulkan driver on Linux. RADV is already the default on Steam Deck, Ubuntu, Fedora, and Arch. If you still have AMDVLK installed, now is a good time to remove it.

Summary

If your Android emulator won’t boot on an AMD GPU on Linux:

1. adb logcat -d -b crash – look for Vulkan crashes
2. vulkaninfo --summary | grep driverName – check your driver
3. If it says “AMD open-source driver”:

   sudo apt remove amdvlk
   

4. Restart Android Studio and the emulator

I wish the emulator surfaced this error somewhere visible instead of silently hanging. But at least the logcat trail is clear once you know to look.

Android Studio’s design panel is not a monolithic system. It is a pluggable framework where each UI technology (Compose, Wear Tiles, Glance AppWidgets, Custom Views) registers its own “designer module” via IntelliJ extension points.

This post uses Wear Tiles and Glance AppWidgets as case studies to show how new Compose-based platforms expand the designer and tooling infrastructure, on both the Android Studio (IDE) side and the AndroidX (library) side. A final section covers Remote Compose, which extends Compose preview without adding a designer module at all.

One thing worth stating up front: non-Google developers can add custom designers to Android Studio without modifying its source code. The extension point architecture is public, stable (unchanged since 2019), and Google’s own designers use it the same way an external plugin would.

Designer module organization (Android Studio side)

Directory structure

All designer modules live under studio-main/tools/adt/idea/:

tools/adt/idea/
├── designer/                  # Core framework — extension points, base classes
│   ├── src/.../multirepresentation/
│   │   ├── PreviewRepresentationProvider.kt    # Master interface
│   │   ├── PreviewRepresentation.kt            # Representation interface
│   │   ├── MultiRepresentationPreview.kt       # Container that queries providers
│   │   └── sourcecode/
│   │       └── SourceCodeEditorProvider.kt     # Auto-discovery via EP
│   ├── customview/            # Custom View preview (sub-module)
│   └── resources/META-INF/designer.xml         # EP definition (line 72)
│
├── preview-designer/          # Shared preview infrastructure
│   └── src/.../preview/
│       ├── find/FilePreviewElementFinder.kt    # Annotation finder interface
│       └── representation/CommonRepresentationEditorFileType.kt
│
├── compose-designer/          # Compose @Preview
│   ├── src/.../ComposePreviewRepresentationProvider.kt
│   ├── src/.../AnnotationFilePreviewElementFinder.kt
│   └── resources/META-INF/compose-designer.xml
│
├── wear-designer/             # Wear Tiles @Preview
│   ├── src/.../WearTilePreviewRepresentationProvider.kt
│   ├── src/.../WearTilePreviewElementFinder.kt
│   └── resources/META-INF/wear-designer.xml
│
└── glance-designer/           # Glance @Preview
    ├── src/.../AppWidgetPreviewRepresentationProvider.kt
    ├── src/.../GlancePreviewElementFinder.kt
    └── resources/META-INF/glance-designer.xml

Module dependency graph

graph TD
    D[designer<br/><i>Core framework</i><br/>EP definition, base interfaces] --> PD[preview-designer<br/><i>Shared infrastructure</i><br/>FilePreviewElementFinder, CommonRepresentation]

    PD --> CD[compose-designer<br/><i>Compose @Preview</i>]
    PD --> WD[wear-designer<br/><i>Wear Tiles @Preview</i>]
    PD --> GD[glance-designer<br/><i>Glance @Preview</i>]
    D --> CV[designer/customview<br/><i>Custom View Preview</i>]

    style D fill:#f9f,stroke:#333
    style PD fill:#bbf,stroke:#333
    style CD fill:#bfb,stroke:#333
    style WD fill:#fbf,stroke:#333
    style GD fill:#ffb,stroke:#333
    style CV fill:#fbb,stroke:#333

What each module provides

Extension point architecture

The master extension point

Defined in designer.xml:70-74:

<!-- Collects all the providers for source code preview representations -->
<extensionPoints>
  <extensionPoint
    qualifiedName="com.android.tools.idea.uibuilder.editor.multirepresentation.sourcecode.sourceCodePreviewRepresentationProvider"
    interface="com.android.tools.idea.uibuilder.editor.multirepresentation.PreviewRepresentationProvider" />
</extensionPoints>

All designer modules register against this single extension point. Any IntelliJ/AS plugin can register an implementation.

PreviewRepresentationProvider Interface

Defined in designer/src/.../PreviewRepresentationProvider.kt:

interface PreviewRepresentationProvider {
  /** A name associated with the representation */
  val displayName: RepresentationName

  /** Tells a client if the corresponding PreviewRepresentation is applicable for the input file. */
  suspend fun accept(project: Project, psiFile: PsiFile): Boolean

  /** Creates a corresponding PreviewRepresentation for the input file. */
  suspend fun createRepresentation(psiFile: PsiFile): PreviewRepresentation
}

Three methods. Implement this interface, register it in plugin.xml, and AS calls your provider whenever a source file is opened.

PreviewRepresentation Interface

Defined in designer/src/.../PreviewRepresentation.kt:

interface PreviewRepresentation : Disposable {
  /** JComponent to display in the preview panel */
  val component: JComponent

  /** Preferred initial visibility (HIDDEN, SPLIT, or FULL) */
  val preferredInitialVisibility: PreferredVisibility?

  // Lifecycle
  fun onActivate() {}
  fun onDeactivate() {}

  // State persistence
  fun setState(state: PreviewRepresentationState) {}
  fun getState(): PreviewRepresentationState? = null

  // Navigation
  val caretNavigationHandler: CaretNavigationHandler

  // Misc
  fun updateNotifications(parentEditor: FileEditor) {}
  fun registerShortcuts(applicableTo: JComponent) {}
  suspend fun hasPreviews(): Boolean = true
  fun hasPreviewsCached() = true
}

The one that matters is component: JComponent. You provide a Swing component, AS embeds it in the split editor. Whatever you put in that JComponent is what the user sees.

Auto-discovery mechanism

SourceCodeEditorProvider.kt:58-60,88:

private const val EP_NAME =
  "com.android.tools.idea.uibuilder.editor.multirepresentation.sourcecode.sourceCodePreviewRepresentationProvider"
private val PROVIDERS_EP = ExtensionPointName.create<PreviewRepresentationProvider>(EP_NAME)

// In constructor:
constructor() : this(PROVIDERS_EP.extensions.toList())

When any source file is opened, SourceCodeEditorProvider:

1. Loads ALL registered PreviewRepresentationProvider implementations via PROVIDERS_EP.extensions.toList()
2. Calls accept(project, psiFile) on each
3. For those that return true, calls createRepresentation(psiFile)
4. Wraps the result in a MultiRepresentationPreview (tabbed container if multiple match)

Flow: file opened → preview shown

sequenceDiagram
    participant User
    participant AS as Android Studio
    participant SCEP as SourceCodeEditorProvider
    participant MRP as MultiRepresentationPreview
    participant P1 as ComposePreviewProvider
    participant P2 as WearTilePreviewProvider
    participant P3 as GlancePreviewProvider

    User->>AS: Opens .kt file
    AS->>SCEP: createEditor(project, file)
    SCEP->>SCEP: PROVIDERS_EP.extensions.toList()
    Note right of SCEP: Discovers ALL registered providers

    par Query each provider
        SCEP->>P1: accept(project, psiFile)
        P1-->>SCEP: true (has @Composable + Compose @Preview)
        SCEP->>P2: accept(project, psiFile)
        P2-->>SCEP: false (no Tile annotations)
        SCEP->>P3: accept(project, psiFile)
        P3-->>SCEP: true (has @Composable + Glance @Preview)
    end

    SCEP->>MRP: Create with [P1, P3]
    MRP->>P1: createRepresentation(psiFile)
    MRP->>P3: createRepresentation(psiFile)
    MRP->>AS: Return tabbed preview (Compose | Glance tabs)
    AS->>User: Show split editor with preview panel

How each designer registers

Registration pattern (4-part)

Every designer follows the same pattern:

Part 1: Plugin XML registration

All use the same XML pattern, registering against the sourceCodePreviewRepresentationProvider EP:

Compose (compose-designer.xml:154-156):

<extensions defaultExtensionNs="com.android.tools.idea.uibuilder">
  <editor.multirepresentation.sourcecode.sourceCodePreviewRepresentationProvider
      implementation="com.android.tools.idea.compose.preview.ComposePreviewRepresentationProvider"/>
</extensions>

Wear (wear-designer.xml:17-19):

<extensions defaultExtensionNs="com.android.tools.idea.uibuilder.editor.multirepresentation.sourcecode">
  <sourceCodePreviewRepresentationProvider
      implementation="com.android.tools.idea.wear.preview.WearTilePreviewRepresentationProvider"/>
</extensions>

Glance (glance-designer.xml:17-19):

<extensions defaultExtensionNs="com.android.tools.idea.uibuilder.editor.multirepresentation.sourcecode">
  <sourceCodePreviewRepresentationProvider
      implementation="com.android.tools.idea.glance.preview.AppWidgetPreviewRepresentationProvider"/>
</extensions>

Note: The namespace differs slightly (Compose uses the shorter com.android.tools.idea.uibuilder prefix because it also registers other extensions), but both resolve to the same EP.

Part 2: accept() logic

A few things to note: Compose has no feature flag and is always enabled, while Wear and Glance are gated behind StudioFlags. Wear Tiles is the only one that supports Java (.isSourceFileType()); Compose and Glance are Kotlin-only. All three accept() methods are suspend, so providers can do index lookups without blocking the EDT.

Part 3: Annotation FQNs

They all share the short name Preview and are disambiguated by FQN. The element finders scan Kotlin/Java annotation indices for these specific qualified names.

Part 4: ViewAdapters (rendering bridge)

The ViewAdapter pattern: AS generates synthetic XML with the adapter as root element, passes the FQN of the preview method as an attribute. LayoutLib inflates the XML, which instantiates the adapter View. The adapter then invokes the preview function and renders the result.

AndroidX library side

Annotation pattern

All three annotations follow the same structure:

@Retention(AnnotationRetention.BINARY)    // Survives compilation
@Target(AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.FUNCTION)  // Multi-Preview support
@Repeatable                               // Multiple previews per function
annotation class Preview(...)

• BINARY retention ensures the annotation is in compiled .class files (needed for index-based discovery)
• ANNOTATION_CLASS target enables Multi-Preview (annotating another annotation with @Preview)
• FUNCTION target is for direct usage on preview methods

Annotation parameters

Wear Tiles has fewer parameters because tiles run on fixed device shapes (round watches). Glance only has widthDp and heightDp since that’s all widget previews need.

ViewAdapter pattern

Each library ships a separate tooling artifact containing a ViewAdapter, a custom View or FrameLayout subclass that:

1. Receives the preview method FQN via XML attributes
2. Reflectively invokes the method
3. Renders the result into itself

Module structure

Each library separates preview support into lightweight artifacts:

compose/ui/
├── ui-tooling-preview/     # @Preview annotation only (tiny, no runtime deps)
├── ui-tooling/             # ComposeViewAdapter + runtime (heavier)
└── ui-tooling-data/        # Preview element data classes

wear/tiles/
├── tiles-tooling-preview/  # @Preview annotation only
└── tiles-tooling/          # TileServiceViewAdapter

glance/
├── glance-preview/         # @Preview annotation only
└── glance-appwidget-preview/  # GlanceAppWidgetViewAdapter

The *-tooling-preview artifacts are intentionally tiny. They contain only the annotation definition and are added as compileOnly dependencies so preview infrastructure stays out of production APKs.

End-to-end flow

sequenceDiagram
    participant Dev as Developer
    participant PSI as PSI / Index
    participant PRP as PreviewRepresentationProvider
    participant PR as PreviewRepresentation
    participant FEF as FilePreviewElementFinder
    participant NlM as NlModel
    participant RS as RenderService
    participant LL as LayoutLib
    participant VA as ViewAdapter
    participant DS as DesignSurface

    Dev->>PSI: Writes @Preview function
    Note over PSI: File change triggers re-index

    PSI->>PRP: accept(project, psiFile)
    PRP->>PSI: Check annotation index for FQN
    PSI-->>PRP: true (annotation found)

    PRP->>PR: createRepresentation(psiFile)
    PR->>FEF: findPreviewElements(project, vFile)
    FEF->>PSI: Walk annotation graph (Multi-Preview)
    PSI-->>FEF: List<PreviewElement>

    PR->>NlM: Create NlModel with synthetic XML
    Note over NlM: XML contains ViewAdapter element<br/>with preview method FQN attribute

    NlM->>RS: requestRender()
    RS->>LL: RenderSession.render()
    LL->>VA: Inflate ViewAdapter from XML
    VA->>VA: Reflectively invoke preview method
    VA->>VA: Render result (Compose/Tile/Widget)
    VA-->>LL: Bitmap result

    LL-->>RS: RenderResult (bitmap + metadata)
    RS-->>PR: Rendered image
    PR->>DS: Display on DesignSurface
    DS->>Dev: Shows preview in split editor

Writing a custom designer plugin

External developers can register their own designer modules using the IntelliJ Platform Plugin SDK. Google’s own Wear Tiles and Glance designers use the same extension point that third-party plugins would; the only difference is theirs ship bundled with AS while yours ships via JetBrains Marketplace or manual install.

Declare a dependency on org.jetbrains.android in your Gradle build to get compile-time access to the designer interfaces:

plugins {
    id 'org.jetbrains.intellij' version '1.16.0'
}

intellij {
    version = '2024.1'
    plugins = ['org.jetbrains.android']
}

Then register your PreviewRepresentationProvider against the same extension point in plugin.xml:

<idea-plugin>
  <depends>org.jetbrains.android</depends>
  <depends>com.intellij.modules.androidstudio</depends>

  <extensions defaultExtensionNs="com.android.tools.idea.uibuilder.editor.multirepresentation.sourcecode">
    <sourceCodePreviewRepresentationProvider
        implementation="com.yourcompany.preview.CustomPreviewRepresentationProvider"/>
  </extensions>
</idea-plugin>

The interfaces have no @ApiStatus.Internal or @RestrictTo annotations and have been stable since 2019 (though not formally semver’d, so pin your plugin’s compatibility range and test against AS Canary). The org.jetbrains.android plugin source is at github.com/JetBrains/android.

Remote Compose (no designer module, player-based preview)

Remote Compose takes a different approach from Wear Tiles and Glance. Instead of adding a designer module to Android Studio with its own PreviewRepresentationProvider, it handles preview support entirely from the library side. Nothing ships in AS.

What Remote Compose is

A client/server UI serialization system (inception 2025, @RestrictTo(LIBRARY_GROUP)) that records Compose-like UI trees into a compact binary opcode stream (custom wire format, not protobuf). A lightweight player renders the stream on a remote device using direct Canvas drawing, without needing a full Compose runtime on the player side.

Two things use it today: Glance AppWidgets (Android 15+) translate the Glance DSL tree into RemoteCompose binary for widget rendering, and Wear Compose Remote Material3 uses remote Material3 components for watch faces and complications.

Why no designer module?

Remote Compose reuses standard Compose @Preview. The preview function is a regular @Composable that captures its content into a binary document and plays it back, all within the same LayoutLib render pass. AS has no idea RemoteCompose is involved; it just sees a @Composable annotated with @Preview.

Architecture: double-render within standard @Preview

sequenceDiagram
    participant Dev as Developer
    participant AS as Android Studio
    participant LL as LayoutLib
    participant CVA as ComposeViewAdapter
    participant RP as RemotePreview()
    participant Cap as RememberRemoteDocumentInline
    participant Player as RemoteDocumentPlayer<br/>(AndroidView → RemoteComposePlayer)

    Dev->>AS: Writes @Preview @Composable fun MyPreview()
    Note over AS: Standard Compose @Preview pipeline
    AS->>LL: RenderSession.render()
    LL->>CVA: Inflate ComposeViewAdapter
    CVA->>RP: Invoke @Preview composable

    Note over RP,Cap: Phase 1: Capture
    RP->>Cap: RememberRemoteDocumentInline(content)
    Cap->>Cap: Sub-composition with<br/>RemoteComposeApplierV2
    Cap->>Cap: Build RemoteComposeNodeV2 tree
    Cap->>Cap: Traverse tree → binary opcodes
    Cap-->>RP: RemoteDocument (byte array)

    Note over RP,Player: Phase 2: Playback
    RP->>Player: RemoteDocPreview(document)
    Player->>Player: AndroidView(RemoteComposePlayer)
    Player->>Player: onDraw(Canvas) → CoreDocument.paint()
    Player-->>LL: Rendered bitmap

    LL-->>AS: Standard preview image
    AS->>Dev: Shows in design panel

The difference from Wear/Glance: standard Compose preview renders composables directly via LayoutLib. Remote Compose preview goes through Compose composition, then binary serialization, then player Canvas rendering, all within the same LayoutLib render pass. The preview shows what the remote player would actually show, not the Compose tree itself.

Capture pipeline (V2)

RemotePreview(content)
  └── RememberRemoteDocumentInline(profile, content)
        ├── Creates RemoteRootNodeV2 as tree root
        ├── Sub-composition with custom RemoteComposeApplierV2
        │     (Compose AbstractApplier — builds node tree bottom-up)
        ├── @RemoteComposable functions emit ComposeNode calls
        │     → create RemoteComposeNodeV2 subtypes
        ├── Traverses tree: node.render(creationState, remoteCanvas)
        │     → emits binary opcodes via RemoteComposeWriter
        └── creationState.document.encodeToByteArray()
              → RemoteDocument passed to RemoteDocPreview()

Player: RemoteDocumentPlayer → AndroidView(RemoteComposePlayer)

Source: remote-player-compose/src/.../RemoteDocumentPlayer.kt:

@Composable
fun RemoteDocumentPlayer(
    document: CoreDocument,
    documentWidth: Int,
    documentHeight: Int,
    modifier: Modifier = Modifier,
    ...
) {
    AndroidView(
        modifier = androidViewModifier,
        factory = { RemoteComposePlayer(it).apply { init(this) } },
        update = { remoteComposePlayer ->
            remoteComposePlayer.setTheme(playbackTheme)
            remoteComposePlayer.setDocument(remoteDoc)
            ...
        },
    )
}

RemoteComposePlayer (extends FrameLayout) → RemoteComposeView (custom View). On draw, it passes the Android Canvas to AndroidRemoteContext, which calls CoreDocument.paint() to walk the operation tree and emit Canvas draw calls. Animation runs through a Choreographer-driven loop with needsRepaint() and an RPN expression engine for player-side computation. Accessibility goes through RemoteComposeDocumentAccessibility, and theming is handled by light/dark filtering during playback.

@RemoteComposable annotation

@Retention(AnnotationRetention.BINARY)
@ComposableTargetMarker(description = "RemoteCompose Composable")
@Target(FUNCTION, PROPERTY_GETTER, TYPE, TYPE_PARAMETER)
public annotation class RemoteComposable

Uses Compose’s @ComposableTargetMarker for compile-time safety, so the compiler flags you if you accidentally mix standard composables with remote ones. Remote components mirror standard Compose: RemoteBox, RemoteRow, RemoteColumn, RemoteText, RemoteImage, RemoteCanvas.

Module structure

compose/remote/
├── remote-core/                    # Binary protocol engine, opcodes, WireBuffer, layout compute
├── remote-creation-core/           # Java procedural API: RemoteComposeWriter, RcPaint, modifiers
├── remote-creation-compose/        # Kotlin Compose DSL: RemoteBox/Row/Column/Text + capture system
├── remote-creation/                # Multiplatform wrapper for creation APIs
├── remote-player-core/             # RemoteDocument (public API), AndroidRemoteContext, state mgmt
├── remote-player-view/             # RemoteComposePlayer (FrameLayout), RemoteComposeView — Canvas renderer
├── remote-player-compose/          # RemoteDocumentPlayer composable — wraps View player via AndroidView()
├── remote-player-compose-testutils/
├── remote-core-testutils/
└── remote-tooling-preview/         # RemotePreview(), RemoteDocPreview() — IDE preview integration

Usage

// Pattern 1: Preview a @RemoteComposable composition (records + plays back)
@Preview @Composable
fun MyWidgetPreview() = RemotePreview {
    RemoteBox(modifier = RemoteModifier.fillMaxSize()) {
        RemoteText("Hello from RemoteCompose")
    }
}

// Pattern 2: Preview a pre-serialized binary document
@Preview @Composable
fun MyDocPreview() = RemoteDocPreview(RemoteDocument(byteArrayFromSomewhere))

What this looks like in practice

Remote Compose extends preview without touching Android Studio at all. The recipe has three parts:

1. A wrapper composable (e.g. RemotePreview()) that captures content via a custom AbstractApplier
2. A player View (e.g. RemoteComposePlayer) that renders the captured content via Canvas
3. AndroidView() to embed the player within standard Compose @Preview

This is Approach B from the custom designers section in practice. You get the standard @Preview panel with no custom tooling, but you also skip all IDE-side work.

Comparison: three extension strategies

Source files reference

1. Executive Summary

Split APKs allow an Android application to be delivered as multiple APK files instead of a single monolithic APK. Introduced in Android L (API 21), split APKs provide:

• Reduced download sizes via config splits (density, ABI, language-specific resources)
• Modular features via feature splits (on-demand delivery of app modules)
• Incremental updates by updating individual splits without replacing the entire app

The system comprises three major subsystems:

1. Parsing - Manifest analysis, validation, and dependency tree construction
2. Installation - Session-based install with staging, sealing, validation, and commit
3. Runtime - ClassLoader hierarchy, resource loading, and component dispatch

2. Architecture Overview

graph TB
    subgraph "Developer Side"
        A[Android App Bundle .aab] --> B[bundletool / Play Store]
        B --> C[Base APK]
        B --> D[Feature Split APKs]
        B --> E[Config Split APKs]
    end

    subgraph "Installation Pipeline"
        F[adb install-multiple / PackageInstaller API]
        F --> G[PackageInstallerSession]
        G --> H["Session Create (allocate sessionId)"]
        H --> I["Session Write (stream APKs to stageDir)"]
        I --> J["Session Seal (prevent mutations)"]
        J --> K["Validate APKs (signatures, versions, splits)"]
        K --> L["InstallPackageHelper.installPackagesTraced()"]
        L --> M["6-Phase Install: Prepare - Scan - Reconcile - Rename - DexOpt - Commit"]
    end

    subgraph "Runtime Loading"
        N[ApplicationInfo.splitSourceDirs]
        N --> O{isolatedSplits?}
        O -->|Yes| P["SplitDependencyLoaderImpl (per-split ClassLoader)"]
        O -->|No| Q["Single ClassLoader (all splits merged)"]
        P --> R[createContextForSplit]
        R --> S[Activity / Service / Receiver / Provider]
        Q --> S
    end

    C --> F
    D --> F
    E --> F
    M --> N

3. Split APK Types

graph LR
    subgraph "Split APK Taxonomy"
        BASE["Base APK (split=null)"]

        subgraph "Feature Splits"
            FS1["Feature Split A (isFeatureSplit=true)"]
            FS2["Feature Split B (isFeatureSplit=true)"]
        end

        subgraph "Config Splits"
            CS1["Config for Base (no configForSplit or empty) e.g., base.xxhdpi.apk"]
            CS2["Config for Feature A (configForSplit=featureA) e.g., featureA.arm64.apk"]
        end
    end

    FS1 -.->|"depends on"| BASE
    FS2 -.->|"depends on"| BASE
    FS1 -.->|"uses-split"| FS2
    CS1 -.->|"config for"| BASE
    CS2 -.->|"config for"| FS1

3.1 Base APK

• The mandatory APK with split attribute absent or null in <manifest>
• Contains the core application code, resources, and AndroidManifest.xml
• All other splits depend on it (directly or transitively)
• Identified by ApkLite.getSplitName() == null

3.2 Feature Splits

• Declared with android:isFeatureSplit="true" in <manifest>
• Contains additional code (activities, services, etc.) and resources
• Can declare dependencies on other feature splits via <uses-split android:name="...">
• If no <uses-split> is declared, implicitly depends on the base APK
• Can define their own <application> tag with components
• Components declared in feature splits get ComponentInfo.splitName set to the split name

3.3 Config Splits

• Non-feature splits with configForSplit attribute (e.g., configForSplit="featureA")
• Contain configuration-specific resources (screen density, ABI, locale)
• Form leaves in the dependency tree (no dependencies of their own)
• Cannot be feature splits (validated in SplitDependencyLoader.createDependenciesFromPackage())

3.4 Required Splits

• Base APK can declare android:isSplitRequired="true"
• Can also specify requiredSplitTypes (e.g., density, abi, language)
• Installation fails with INSTALL_FAILED_MISSING_SPLIT if required splits are missing
• Validated in PackageInstallerSession.validateApkInstallLocked() (method at line 4465, required split check at line 4700)

4. Manifest Structure

4.1 Key Manifest Attributes

4.2 Uses-Split Declaration

<!-- In a feature split's AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app"
    split="featureB"
    android:isFeatureSplit="true">

    <!-- Declares dependency on featureA -->
    <uses-split android:name="featureA" />

    <application android:hasCode="true">
        <activity android:name=".FeatureBActivity" />
    </application>
</manifest>

4.3 Config Split Declaration

<!-- Config split for density resources of featureA -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.app"
    split="featureA.config.xxhdpi"
    configForSplit="featureA">
</manifest>

4.4 Parsing Flow - parsePackageSplitNames

Source: ApkLiteParseUtils.java:900

// Extracts package name and split name from <manifest> tag
public static ParseResult<Pair<String, String>> parsePackageSplitNames(
        ParseInput input, XmlResourceParser parser) {
    // Reads "package" attribute for package name
    // Reads "split" attribute for split name
    // Returns Pair<packageName, splitName>
}

5. Parsing Infrastructure

5.1 Two-Phase Parsing

flowchart TD
    A["APK File(s)"] --> B{"Single file or directory?"}
    B -->|"Single file"| C["parseMonolithicPackageLite()"]
    B -->|"Directory"| D["parseClusterPackageLite()"]

    C --> E["parseApkLite() - Phase 1: Lightweight parse"]
    D --> F["Iterate all .apk files in dir"]
    F --> E

    E --> G["PackageLite (metadata only)"]

    G --> H["ParsingPackageUtils.parseClusterPackage() - Phase 2: Full parse"]
    H --> I["parseBaseApk() - Parse base manifest"]
    H --> J["parseSplitApk() x N - Parse each split manifest"]

    I --> K["ParsingPackage (complete package info)"]
    J --> K

    subgraph "Phase 1: Lightweight"
        E
        G
    end

    subgraph "Phase 2: Full Parse"
        H
        I
        J
        K
    end

5.2 Phase 1: Lightweight Parsing (ApkLiteParseUtils)

Entry Point: ApkLiteParseUtils.parsePackageLite() (line 115)

• If path is a directory: calls parseClusterPackageLite() (line 180)
  • Iterates all .apk files
  • Calls parseApkLite() on each file
  • Validates package name consistency across all APKs
  • Validates version code consistency across all APKs
  • Rejects duplicate split names
  • Base APK identified by splitName == null (removed from map via apks.remove(null))
  • Sorts splits by name using SplitNameComparator
  • Composes PackageLite with all split metadata
• If path is a single file: calls parseMonolithicPackageLite() (line 127)
  • Single APK, no splits

Key data extracted per APK (ApkLite fields):

• splitName, packageName, versionCode
• isFeatureSplit, configForSplit, usesSplitName
• isSplitRequired, requiredSplitTypes, splitTypes
• signingDetails, targetSdkVersion, minSdkVersion

5.3 Phase 2: Full Parsing (ParsingPackageUtils)

Entry Point: ParsingPackageUtils.parseClusterPackage() (line ~370)

// 1. Build dependency tree (if isolated splits)
SparseArray<int[]> splitDependencies =
    SplitAssetDependencyLoader.createDependenciesFromPackage(lite);

// 2. Choose asset loader
if (lite has isolatedSplits && dependencies exist) {
    assetLoader = new SplitAssetDependencyLoader(lite, splitDependencies, flags);
} else {
    assetLoader = new DefaultSplitAssetLoader(lite, flags);
}

// 3. Parse base APK
parseBaseApk(input, baseApk, codePath, assetLoader, flags, ...);

// 4. Register splits metadata
pkg.asSplit(splitNames, splitApkPaths, splitRevisionCodes, splitDependencies);

// 5. Parse each split APK
for (int i = 0; i < splitCount; i++) {
    parseSplitApk(input, pkg, i, assetLoader.getSplitAssetManager(i), flags);
}

5.4 Split APK Parsing Details (parseSplitApplication)

Source: ParsingPackageUtils.java:841

Split APKs can declare these components in their <application> tag:

• <activity> and <receiver> (via ParsedActivityUtils)
• <service> (via ParsedServiceUtils)
• <provider> (via ParsedProviderUtils)
• <activity-alias>

Critical: The defaultSplitName (line 865) is set from pkg.getSplitNames()[splitIndex] and passed to all component parsers. This sets each component’s splitName field for runtime dispatch.

5.5 SplitAssetLoader Implementations

classDiagram
    class SplitAssetLoader {
        <<interface>>
        +getBaseAssetManager() AssetManager
        +getSplitAssetManager(int splitIdx) AssetManager
        +getBaseApkAssets() ApkAssets
    }

    class DefaultSplitAssetLoader {
        -mBaseApkPath : String
        -mSplitApkPaths : String array
        -mCachedAssetManager : AssetManager
        +getBaseAssetManager() AssetManager
        +getSplitAssetManager(int) AssetManager
    }

    class SplitAssetDependencyLoader {
        -mSplitPaths : String array
        -mCachedSplitApks : ApkAssets 2D array
        -mCachedAssetManagers : AssetManager array
        #isSplitCached(int) boolean
        #constructSplit(int, int array, int) void
    }

    class SplitDependencyLoader~E~ {
        <<abstract>>
        -mDependencies : SparseArray of int array
        #loadDependenciesForSplit(int) void
        #isSplitCached(int) boolean
        #constructSplit(int, int array, int) void
    }

    SplitAssetLoader <|.. DefaultSplitAssetLoader
    SplitAssetLoader <|.. SplitAssetDependencyLoader
    SplitDependencyLoader <|-- SplitAssetDependencyLoader

• DefaultSplitAssetLoader: Loads ALL APKs (base + all splits) into a single AssetManager. Used when isolatedSplits is disabled. Every call to getSplitAssetManager() returns the same shared instance.

• SplitAssetDependencyLoader: Creates per-split AssetManager instances that only include the split’s dependency chain. Used when isolatedSplits is enabled. Each split gets an AssetManager containing: parent’s assets + split’s own assets + config split assets.

6. Installation Flow

6.1 End-to-End Installation Sequence

sequenceDiagram
    participant ADB as adb / App Store
    participant PI as PackageInstaller
    participant PIS as PackageInstallerSession
    participant IPH as InstallPackageHelper
    participant PMS as PackageManagerService

    Note over ADB,PMS: Phase 1: Session Creation
    ADB->>PI: createSession(SessionParams)
    PI->>PIS: new PackageInstallerSession()
    PI-->>ADB: sessionId

    Note over ADB,PMS: Phase 2: Stream APKs
    ADB->>PIS: openWrite("base.apk")
    ADB->>PIS: write(base APK bytes)
    ADB->>PIS: openWrite("split_feature.apk")
    ADB->>PIS: write(feature split bytes)

    Note over ADB,PMS: Phase 3: Commit
    ADB->>PIS: commit(statusReceiver)
    PIS->>PIS: markAsSealed()
    PIS->>PIS: sealLocked()
    PIS->>PIS: validateApkInstallLocked()

    Note over PIS: Validation: signatures, versions, split names, required splits

    PIS->>IPH: installPackagesTraced(requests)

    Note over IPH,PMS: Phase 4: 6-Step Install
    IPH->>IPH: prepareInstallPackages()
    IPH->>IPH: scanInstallPackages()
    IPH->>IPH: reconcileInstallPackages()
    IPH->>IPH: renameAndUpdatePaths()
    IPH->>IPH: prepPerformDexoptIfNeeded()
    IPH->>IPH: commitInstallPackages()

    IPH-->>PIS: Install result
    PIS-->>ADB: STATUS_SUCCESS / STATUS_FAILURE

6.2 Session Modes

MODE_FULL_INSTALL

• Complete replacement of all APKs
• Must include a base APK (stagedSplits.contains(null) validated at line 4691)
• All existing splits are replaced
• If isSplitRequired, validates required split types are present (line 4700)
• Creates PackageLite from staged files only

MODE_INHERIT_EXISTING

• Partial update - add, replace, or remove individual splits
• Requires an existing installation (pkgInfo != null, line 4483-4486)
• Inherits base APK if not overridden (line 4736-4738)
• Inherits existing splits if not overridden or removed (line 4750-4764)
• Validates signatures match existing installation (line 4730)
• Validates package name and version code consistency

6.3 Split Validation (validateApkInstallLocked)

Source: PackageInstallerSession.java:4465

flowchart TD
    A["validateApkInstallLocked()"] --> B["Parse all staged APKs via getAddedApkLitesLocked()"]
    B --> C{"Any duplicate split names?"}
    C -->|Yes| FAIL1["INSTALL_FAILED_INVALID_APK"]
    C -->|No| D{"Package name consistent?"}
    D -->|No| FAIL2["INSTALL_FAILED_INVALID_APK"]
    D -->|Yes| E{"Version code consistent?"}
    E -->|No| FAIL3["INSTALL_FAILED_INVALID_APK"]
    E -->|Yes| F{"Signing details match?"}
    F -->|No| FAIL4["INSTALL_FAILED_INVALID_APK"]
    F -->|Yes| G["Rename APKs to canonical names"]
    G --> H{"MODE_FULL_INSTALL?"}
    H -->|Yes| I{"Base APK present?"}
    I -->|No| FAIL5["INSTALL_FAILED_INVALID_APK: Full install must include base"]
    I -->|Yes| J{"Required splits satisfied?"}
    J -->|No| FAIL6["INSTALL_FAILED_MISSING_SPLIT"]
    J -->|Yes| SUCCESS["Compose PackageLite - validation passed"]
    H -->|No| K["MODE_INHERIT_EXISTING"]
    K --> L["Inherit non-replaced, non-removed splits"]
    L --> M["Verify inherited signatures match"]
    M --> SUCCESS

6.4 Split Removal

Splits can be removed during MODE_INHERIT_EXISTING installs:

1. Client writes a remove marker file (filename = splitName + REMOVE_MARKER_EXTENSION)
2. During validation, getRemovedFilesLocked() collects these markers
3. Removed splits are excluded from inheritance (line 4754-4756)
4. Validates that the split being removed actually exists in the current install (line 4600-4605)

6.5 APK Naming Convention

Source: ApkLiteParseUtils.splitNameToFileName() (line 328)

After validation, APKs are renamed to a canonical format:

• Base APK: base.apk
• Split APK: split_<splitName>.apk (e.g., split_featureA.apk)

6.6 6-Phase Install Process (InstallPackageHelper)

Source: InstallPackageHelper.installPackagesTraced() (line 1027)

7. Runtime Loading

7.1 Two Loading Modes

flowchart TD
    A["App Launch"] --> B["LoadedApk created with ApplicationInfo"]
    B --> C{"aInfo.requestsIsolatedSplitLoading()?"}

    C -->|"No (default)"| D["Non-Isolated Mode"]
    D --> D1["All split DEX files added to single ClassLoader"]
    D --> D2["All split resources merged into single ResourcesImpl"]
    D --> D3["createContextForSplit returns this (no-op)"]

    C -->|"Yes (isolatedSplits=true)"| E["Isolated Mode"]
    E --> E1["SplitDependencyLoaderImpl created"]
    E1 --> E2["Per-split ClassLoader hierarchy"]
    E1 --> E3["Per-split resource paths"]
    E1 --> E4["createContextForSplit creates new ContextImpl"]

7.2 Non-Isolated Loading (Default)

When android:isolatedSplits is not set (the default):

• LoadedApk initializes mSplitLoader = null (no dependency loader)
• All split APK paths from ApplicationInfo.splitSourceDirs are added to the base ClassLoader’s classpath
• Resources from all splits are merged into a single ResourcesImpl
• createContextForSplit() returns this (no-op) since all code/resources already available
• getSplitClassLoader() returns the single mClassLoader

Source: LoadedApk.java lines 454, 523-525, 757-761

7.3 Isolated Split Loading

When android:isolatedSplits="true" is declared in the base APK:

• LoadedApk creates mSplitLoader = new SplitDependencyLoaderImpl(aInfo.splitDependencies) (line 455)
• Each split gets its own ClassLoader with parent = the ClassLoader of its dependency
• Each split gets its own resource path set = parent’s resources + split’s resources + config splits

7.4 ClassLoader Hierarchy

Source: LoadedApk.SplitDependencyLoaderImpl.constructSplit() (line 695)

graph BT
    BOOT["BootClassLoader"] --> BASE["Base ClassLoader (PathClassLoader)"]
    BASE --> FA["Feature A ClassLoader"]
    BASE --> FB["Feature B ClassLoader"]
    FA --> FC["Feature C ClassLoader (uses-split: featureA)"]

    style BOOT fill:#e0e0e0
    style BASE fill:#bbdefb
    style FA fill:#c8e6c9
    style FB fill:#c8e6c9
    style FC fill:#fff9c4

Construction algorithm (simplified):

void constructSplit(int splitIdx, int[] configSplitIndices, int parentSplitIdx) {
    if (splitIdx == 0) {
        // Base: use the app's main ClassLoader
        mCachedClassLoaders[0] = mClassLoader;
        mCachedResourcePaths[0] = [config split paths for base];
        return;
    }

    // Get parent's ClassLoader (always valid at this point)
    ClassLoader parent = mCachedClassLoaders[parentSplitIdx];

    // Create new ClassLoader with parent chain
    mCachedClassLoaders[splitIdx] = ApplicationLoaders.getDefault().getClassLoader(
        mSplitAppDirs[splitIdx - 1],  // DEX path for this split
        targetSdkVersion,
        false, null, null,
        parent,                         // Parent ClassLoader
        mSplitClassLoaderNames[splitIdx - 1]  // Custom classloader name
    );

    // Resource paths = parent's paths + this split's path + config split paths
    mCachedResourcePaths[splitIdx] = [
        ...mCachedResourcePaths[parentSplitIdx],
        mSplitResDirs[splitIdx - 1],
        ...config split resource dirs
    ];
}

7.5 Component Dispatch with Splits

sequenceDiagram
    participant AMS as ActivityManagerService
    participant AT as ActivityThread
    participant LA as LoadedApk
    participant CI as ContextImpl

    Note over AMS: Component has ComponentInfo.splitName set
    AMS->>AT: scheduleTransaction(LaunchActivityItem)

    AT->>LA: makeApplication()
    AT->>AT: app.getBaseContext()

    alt splitName != null
        AT->>CI: createContextForSplit(splitName)
        CI->>LA: getSplitClassLoader(splitName)
        LA->>LA: mSplitLoader.ensureSplitLoaded(splitName)
        Note over LA: Traverses dependency tree, loads all parents first
        LA-->>CI: splitClassLoader
        CI->>CI: new ContextImpl(splitClassLoader, splitResourcePaths)
        CI-->>AT: splitContext
    else splitName == null
        Note over AT: Use base context as-is
    end

    AT->>AT: classLoader.loadClass(activityName)
    AT->>AT: instantiate and attach

7.6 How Each Component Type Handles Splits

Activities

Source: ContextImpl.createActivityContext() (line 3618) called from ActivityThread.performLaunchActivity() (line 4335)

Unlike other components, Activity split handling happens inside ContextImpl.createActivityContext() rather than in ActivityThread directly:

// ContextImpl.java line 3626
if (packageInfo.getApplicationInfo().requestsIsolatedSplitLoading()) {
    classLoader = packageInfo.getSplitClassLoader(activityInfo.splitName);
    splitDirs = packageInfo.getSplitPaths(activityInfo.splitName);
}

The Activity is instantiated using the split’s ClassLoader and given a Context with the split’s resources. The split-aware ClassLoader and resource paths are wired into the ContextImpl before it is passed to the Activity.

Services

Source: ActivityThread.java - handleCreateService() (line 5505)

// Line 5518
if (data.info.splitName != null) {
    cl = packageInfo.getSplitClassLoader(data.info.splitName);
}
// Line 5527
if (data.info.splitName != null) {
    context = (ContextImpl) context.createContextForSplit(data.info.splitName);
}

Broadcast Receivers

Source: ActivityThread.java - handleReceiver() (line 5244, split handling at line 5261)

if (data.info.splitName != null) {
    context = (ContextImpl) context.createContextForSplit(data.info.splitName);
}
java.lang.ClassLoader cl = context.getClassLoader();
receiver = packageInfo.getAppFactory().instantiateReceiver(cl, data.info.name, data.intent);

Content Providers

Source: ActivityThread.java (around line 8939)

if (info.splitName != null) {
    c = c.createContextForSplit(info.splitName);
}

7.7 createContextForSplit Implementation

Source: ContextImpl.java:2962

public Context createContextForSplit(String splitName) throws NameNotFoundException {
    if (!mPackageInfo.getApplicationInfo().requestsIsolatedSplitLoading()) {
        return this;  // No-op if isolated splits not enabled
    }

    final ClassLoader classLoader = mPackageInfo.getSplitClassLoader(splitName);
    final String[] paths = mPackageInfo.getSplitPaths(splitName);

    // Create new ContextImpl with split-specific ClassLoader
    final ContextImpl context = new ContextImpl(this, mMainThread, mPackageInfo, mParams,
            ..., splitName, ..., classLoader, null, ...);

    // Create Resources with split-specific resource paths
    context.setResources(ResourcesManager.getInstance().getResources(
            mToken, mPackageInfo.getResDir(), paths, ...));

    return context;
}

8. Dependency Tree System

8.1 Data Structure

The dependency tree is stored as SparseArray<int[]> where:

• Key: Split index (0 = base, 1+ = splits offset by 1)
• Value: Array of dependencies where:
  • [0] = Parent split index (feature dependency via <uses-split>, or -1 for base)
  • [1..N] = Config split indices (leaf dependencies via configForSplit)

8.2 Tree Construction

Source: SplitDependencyLoader.createDependenciesFromPackage() (line 161)

flowchart TD
    A["createDependenciesFromPackage(PackageLite)"] --> B["Initialize: base depends on nothing: put(0, new int[]{-1})"]

    B --> C["Phase 1: Process feature splits"]
    C --> D{"For each feature split"}
    D --> E{"Has uses-split?"}
    E -->|Yes| F["Find target split by name via binary search"]
    E -->|No| G["Implicitly depends on base (index 0)"]
    F --> H["put(splitIdx+1, new int[]{targetIdx})"]
    G --> H

    H --> I["Phase 2: Process config splits"]
    I --> J{"For each non-feature split"}
    J --> K{"Has configForSplit?"}
    K -->|Yes| L["Find target feature split by name"]
    K -->|No| M["Config for base (index 0)"]
    L --> N{"Target is a feature split?"}
    N -->|No| FAIL["IllegalDependencyException"]
    N -->|Yes| O["Append to target's dependency array"]
    M --> O

    O --> P["Phase 3: Cycle detection"]
    P --> Q["For each split, follow first dependency"]
    Q --> R{"Visited before?"}
    R -->|Yes| FAIL2["IllegalDependencyException: Cycle detected"]
    R -->|No| S["Mark visited, continue"]
    S --> T["Return splitDependencies"]

8.3 Dependency Tree Example

graph TD
    subgraph "Example App Split Dependencies"
        BASE["Base APK (idx=0)"]

        BASE --> FS_A["Feature A (idx=1)"]
        BASE --> FS_B["Feature B (idx=2)"]
        FS_A --> FS_C["Feature C (idx=3, uses-split: featureA)"]

        BASE -.-> CS_BASE_HDPI["base.config.hdpi (idx=4, config for base)"]
        BASE -.-> CS_BASE_ARM64["base.config.arm64 (idx=5, config for base)"]
        FS_A -.-> CS_FA_HDPI["featureA.config.hdpi (idx=6, config for featureA)"]
    end

    style BASE fill:#bbdefb,stroke:#1976d2
    style FS_A fill:#c8e6c9,stroke:#388e3c
    style FS_B fill:#c8e6c9,stroke:#388e3c
    style FS_C fill:#fff9c4,stroke:#fbc02d
    style CS_BASE_HDPI fill:#f3e5f5,stroke:#7b1fa2
    style CS_BASE_ARM64 fill:#f3e5f5,stroke:#7b1fa2
    style CS_FA_HDPI fill:#f3e5f5,stroke:#7b1fa2

Resulting SparseArray<int[]>:

8.4 Dependency Loading Algorithm

Source: SplitDependencyLoader.loadDependenciesForSplit() (line 61)

loadDependenciesForSplit(splitIdx=3):  // Loading Feature C
  1. Check: is split 3 cached? No -> continue
  2. Build linear dependency chain (leaf to root):
     - Start: [3]  (Feature C)
     - Follow deps[0]: split 3 depends on split 1 (Feature A)
     - Is split 1 cached? No -> add: [3, 1]
     - Follow deps[0]: split 1 depends on split 0 (Base)
     - Is split 0 cached? No -> add: [3, 1, 0]
     - Split 0 deps[0] = -1 -> stop
  3. Visit right-to-left (root to leaf):
     - constructSplit(0, configSplits=[4,5], parentIdx=-1)  // Build Base
     - constructSplit(1, configSplits=[6], parentIdx=0)      // Build Feature A
     - constructSplit(3, configSplits=[], parentIdx=1)        // Build Feature C

9. Android App Bundle (AAB) and Split APKs

9.1 Relationship Overview

The Android App Bundle (.aab) and Split APKs are two sides of the same coin. The AAB is the publishing format that developers upload; Split APKs are the delivery format that devices receive and install. The AOSP framework only knows about Split APKs – it has no concept of AABs at runtime.

flowchart LR
    subgraph "Developer"
        SRC["App Source Code"] --> GRADLE["Android Gradle Plugin"]
        GRADLE --> AAB[".aab (App Bundle)"]
    end

    subgraph "Distribution (Google Play / bundletool)"
        AAB --> BT["bundletool / Play Store"]
        BT --> |"Generate for device config"| APKS["Split APK Set (.apks)"]

        APKS --> BASE_APK["base.apk"]
        APKS --> CFG_DENSITY["split_config.xxhdpi.apk"]
        APKS --> CFG_ABI["split_config.arm64_v8a.apk"]
        APKS --> CFG_LANG["split_config.en.apk"]
        APKS --> FEAT["split_featureX.apk"]
        APKS --> FEAT_CFG["split_featureX.config.xxhdpi.apk"]
    end

    subgraph "Device (AOSP Framework)"
        PI["PackageInstaller Session API"]
        PI --> PIS["PackageInstallerSession"]
        PIS --> IPH["InstallPackageHelper"]
        IPH --> INSTALLED["/data/app/..."]
    end

    BASE_APK --> PI
    CFG_DENSITY --> PI
    CFG_ABI --> PI
    CFG_LANG --> PI
    FEAT --> PI
    FEAT_CFG --> PI

9.2 AAB Structure vs Split APK Structure

An AAB is essentially a structured ZIP containing modules, each of which maps to one or more split APKs when delivered to a device.

graph TB
    subgraph "Android App Bundle (.aab)"
        direction TB
        BASE_MOD["base/ module"]
        BASE_MOD --> B_MANIFEST["manifest/AndroidManifest.xml"]
        BASE_MOD --> B_DEX["dex/classes.dex"]
        BASE_MOD --> B_RES["res/ (all densities, all languages)"]
        BASE_MOD --> B_NATIVE["lib/ (all ABIs)"]
        BASE_MOD --> B_ASSETS["assets/"]

        FEAT_MOD["featureX/ module"]
        FEAT_MOD --> F_MANIFEST["manifest/AndroidManifest.xml"]
        FEAT_MOD --> F_DEX["dex/classes.dex"]
        FEAT_MOD --> F_RES["res/"]

        BUNDLE_META["BundleConfig.pb"]
    end

    subgraph "Generated Split APKs (for a specific device)"
        direction TB
        S_BASE["base.apk (code + default resources)"]
        S_CFG_D["split_config.xxhdpi.apk (density resources)"]
        S_CFG_A["split_config.arm64_v8a.apk (native libs)"]
        S_CFG_L["split_config.en.apk (language strings)"]
        S_FEAT["split_featureX.apk (feature code + default res)"]
        S_FEAT_D["split_featureX.config.xxhdpi.apk (feature density)"]
    end

    BASE_MOD ==>|"bundletool generates"| S_BASE
    BASE_MOD ==>|"split by density"| S_CFG_D
    BASE_MOD ==>|"split by ABI"| S_CFG_A
    BASE_MOD ==>|"split by language"| S_CFG_L
    FEAT_MOD ==>|"becomes feature split"| S_FEAT
    FEAT_MOD ==>|"split by density"| S_FEAT_D

9.3 How bundletool Generates Split APKs

The bundletool (external to AOSP) converts an AAB into split APKs. The naming and format conventions AOSP expects:

Split Naming Convention

bundletool generates split names that follow the pattern the AOSP parser expects:

The AOSP framework canonicalizes filenames via ApkLiteParseUtils.splitNameToFileName() (line 328):

final String fileName = apk.getSplitName() == null
    ? "base" : "split_" + apk.getSplitName();
return fileName + ".apk";

Manifest Attributes Generated by bundletool

For a base APK:

<manifest package="com.example.app"
    android:versionCode="42"
    android:isSplitRequired="true"
    android:requiredSplitTypes="density,abi,language"
    android:isolatedSplits="true">

For a config split for the base (e.g., density — configForSplit absent means it targets the base):

<manifest package="com.example.app"
    split="config.xxhdpi"
    android:splitTypes="density">

For a config split for a feature (e.g., density for featureA):

<manifest package="com.example.app"
    split="featureA.config.xxhdpi"
    configForSplit="featureA"
    android:splitTypes="density">

For a feature split:

<manifest package="com.example.app"
    split="featureX"
    android:isFeatureSplit="true">
    <uses-split android:name="featureY" />  <!-- if depends on another feature -->
    <application android:hasCode="true">
        <activity android:name=".FeatureActivity" />
    </application>
</manifest>

For a feature’s config split:

<manifest package="com.example.app"
    split="featureX.config.xxhdpi"
    configForSplit="featureX"
    android:splitTypes="density">
</manifest>

9.4 requiredSplitTypes and splitTypes – The AAB Contract

The requiredSplitTypes / splitTypes mechanism is the formal contract between AAB-generated APKs and the AOSP installation validator.

Source: attrs_manifest.xml (lines 1304-1318)

flowchart TD
    A["Base APK declares: requiredSplitTypes=density,abi,language"] --> B["PackageInstallerSession.validateApkInstallLocked()"]
    B --> C["Collect stagedSplitTypes from all splits"]
    C --> D{"stagedSplitTypes.containsAll(requiredSplitTypes)?"}
    D -->|"Yes: density,abi,language all present"| E["Installation proceeds"]
    D -->|"No: missing language split"| F["INSTALL_FAILED_MISSING_SPLIT"]

How it works:

1. Base APK declares android:requiredSplitTypes="density,abi,language" – types that must be present
2. Each config split declares android:splitTypes="density" (or "abi", "language") – types it provides
3. During installation, PackageInstallerSession.validateApkInstallLocked() (line 4700) verifies:

   if (baseApk.isSplitRequired() && (stagedSplits.size() <= 1
           || !stagedSplitTypes.containsAll(requiredSplitTypes))) {
       throw new PackageManagerException(INSTALL_FAILED_MISSING_SPLIT,
               "Missing split for " + mPackageName);
   }
   

This prevents installation of an AAB-based app without the required resource splits, which would cause runtime crashes from missing resources.

9.5 AAB Dynamic Feature Modules and Feature Splits

AAB dynamic feature modules map directly to AOSP feature splits:

On-demand delivery flow:

sequenceDiagram
    participant App as App (Play Core SDK)
    participant Play as Google Play Store
    participant PI as PackageInstaller
    participant PMS as PackageManagerService

    App->>Play: SplitInstallManager.startInstall("featureX")
    Play->>Play: Download featureX split APKs for device config
    Play->>PI: createSession(MODE_INHERIT_EXISTING)
    PI-->>Play: sessionId

    Play->>PI: session.write("split_featureX.apk")
    Play->>PI: session.write("split_featureX.config.xxhdpi.apk")
    Play->>PI: session.commit()

    PI->>PMS: Validate and install
    Note over PMS: Inherits existing base + config splits, adds new feature split

    PMS-->>PI: SUCCESS
    PI-->>Play: STATUS_SUCCESS
    Play-->>App: SplitInstallSessionState(INSTALLED)

    App->>App: SplitCompat.installActivity(context)
    App->>App: startActivity(FeatureXActivity)
    Note over App: ActivityThread loads split via ComponentInfo.splitName

Key difference: The on-demand delivery and SplitInstallManager API are part of Google Play Services / Play Core SDK, not part of AOSP. AOSP only provides the underlying PackageInstaller session API that Play uses. The framework handles the incremental split installation via MODE_INHERIT_EXISTING.

9.6 aapt2’s Role in the Build Pipeline

aapt2 (in AOSP) supports the AAB workflow through two key features:

1. Proto format output for bundletool (aapt2 link --proto-format):

Source: frameworks/base/tools/aapt2/cmd/Link.h (line 233-236)

--proto-format    Generates compiled resources in Protobuf format.
                  Suitable as input to the bundle tool for generating an App Bundle.

The Gradle plugin invokes aapt2 link --proto-format to produce proto-format resource tables that bundletool packages into the AAB.

2. Resource table splitting (aapt2 link --split):

Source: frameworks/base/tools/aapt2/cmd/Link.h (line 318-322)

--split  Split resources matching a set of configs out to a Split APK.
         Syntax: path/to/output.apk:<config>[,<config>[...]]

The TableSplitter class (frameworks/base/tools/aapt2/split/TableSplitter.h) splits resource tables based on SplitConstraints (configuration filters like density, locale). This is used both directly and by bundletool to generate config splits.

9.7 End-to-End: From Source Code to Running on Device

flowchart TB
    subgraph "Build Time"
        A1["Source Code + Resources"] --> A2["Android Gradle Plugin"]
        A2 --> A3["aapt2 link --proto-format"]
        A3 --> A4["R8/D8 (DEX compilation)"]
        A4 --> A5[".aab (App Bundle)"]
    end

    subgraph "Distribution Time"
        A5 --> B1["Upload to Google Play"]
        B1 --> B2["Play signs with distribution key"]
        B2 --> B3["Device requests app install"]
        B3 --> B4["Play runs bundletool for device config"]
        B4 --> B5["Generate optimized split APK set"]
    end

    subgraph "Install Time (AOSP)"
        B5 --> C1["PackageInstaller.createSession(MODE_FULL_INSTALL)"]
        C1 --> C2["session.write() for each split APK"]
        C2 --> C3["session.commit()"]
        C3 --> C4["PackageInstallerSession.validateApkInstallLocked()"]
        C4 --> C5["Verify: signatures, versions, requiredSplitTypes"]
        C5 --> C6["InstallPackageHelper: scan, reconcile, dexopt, commit"]
        C6 --> C7["Stored in /data/app/"]
    end

    subgraph "Runtime (AOSP)"
        C7 --> D1["ApplicationInfo populated with splitSourceDirs"]
        D1 --> D2["LoadedApk creates ClassLoaders"]
        D2 --> D3{"isolatedSplits?"}
        D3 -->|Yes| D4["Per-split ClassLoader + Resources"]
        D3 -->|No| D5["All merged into single ClassLoader"]
        D4 --> D6["Component launched via splitName dispatch"]
        D5 --> D6
    end

9.8 What AOSP Knows vs What It Does Not

The AOSP framework is intentionally agnostic to AABs. It provides the low-level primitives (session-based install, split validation, isolated classloading) that any distribution system – Google Play, alternative stores, or adb – can use to deliver and install split APKs.

10. On-Disk Storage

10.1 Installed Package Directory Structure

/data/app/~~<random>/com.example.app-<random>/
    base.apk                        # Base APK
    split_featureA.apk              # Feature split A
    split_featureB.apk              # Feature split B
    split_featureA.config.hdpi.apk  # Config split for featureA
    split_config.arm64_v8a.apk      # ABI config split for base
    split_config.en.apk             # Language config split for base
    lib/
        arm64/                      # ISA-specific subdirectory
            libnative.so            # Extracted native libraries
    oat/
        arm64/                      # ISA-specific subdirectory
            base.odex               # Ahead-of-time compiled base
            base.vdex               # Verified DEX for base
            split_featureA.odex     # AOT compiled feature A
            split_featureA.vdex     # Verified DEX for feature A

How the Final Path Is Constructed

Source: PackageManagerServiceUtils.java - getNextCodePath() (line 1139)

The two-level random directory structure is built using SecureRandom and Base64 encoding:

// PackageManagerServiceUtils.java:1139-1169
public static File getNextCodePath(File targetDir, String packageName) {
    SecureRandom random = new SecureRandom();
    byte[] bytes = new byte[16];

    // First level: ~~<random>
    File firstLevelDir;
    do {
        random.nextBytes(bytes);
        String firstLevelDirName = RANDOM_DIR_PREFIX   // "~~"
                + Base64.encodeToString(bytes, Base64.URL_SAFE | Base64.NO_WRAP);
        firstLevelDir = new File(targetDir, firstLevelDirName);
    } while (firstLevelDir.exists());

    // Second level: <packageName>-<random>
    random.nextBytes(bytes);
    String dirName = packageName + RANDOM_CODEPATH_PREFIX  // '-'
            + Base64.encodeToString(bytes, Base64.URL_SAFE | Base64.NO_WRAP);
    return new File(firstLevelDir, dirName);
}

PackageManagerService.java defines these constants (lines 568-569):

static final String RANDOM_DIR_PREFIX = "~~";
static final char RANDOM_CODEPATH_PREFIX = '-';

The target directory resolves to /data/app via Environment.getDataAppDirectory() (Environment.java:600).

10.2 Staging Directory Lifecycle

flowchart TD
    A["PackageInstallerService.buildTmpSessionDir()
    line 1387"] --> B["/data/app/vmdl<sessionId>.tmp/"]
    B --> C["prepareStageDir(): Os.mkdir() mode 0775
    + SELinux restorecon
    line 1405"]
    C --> D["APKs written via openWrite()"]
    D --> E["validateApkInstallLocked():
    rename to canonical names
    line 4550"]
    E --> F["InstallPackageHelper.renameAndUpdatePaths():
    Os.rename() to final path
    line 2293"]
    F --> G["/data/app/~~<random>/pkg-<random>/"]

Stage 1: Staging Directory Creation

Source: PackageInstallerService.java - buildTmpSessionDir() (line 1387)

// PackageInstallerService.java:1387-1389
private File buildTmpSessionDir(int sessionId, String volumeUuid) {
    final File sessionStagingDir = getTmpSessionDir(volumeUuid);  // /data/app
    return new File(sessionStagingDir, "vmdl" + sessionId + ".tmp");
}

The staging directory is prepared with prepareStageDir() (line 1405), which creates the directory with mode 0775 and applies SELinux context via SELinux.restorecon().

Stage 2: APK File Rename to Canonical Names

Source: PackageInstallerSession.java - validateApkInstallLocked() (lines 4550-4571)

During validation, each APK is renamed to its canonical name using splitNameToFileName():

// PackageInstallerSession.java:4550-4571
final String targetName = ApkLiteParseUtils.splitNameToFileName(apk);
final File targetFile = new File(stageDir, targetName);
resolveAndStageFileLocked(sourceFile, targetFile, apk.getSplitName(), ...);

This produces:

• Base APK → base.apk
• Split APK → split_<splitName>.apk

The naming logic is in ApkLiteParseUtils.splitNameToFileName() (line 328):

final String fileName = apk.getSplitName() == null ? "base" : "split_" + apk.getSplitName();
return fileName + APK_FILE_EXTENSION;

Stage 3: Atomic Rename to Final Path

Source: InstallPackageHelper.java - renameAndUpdatePaths() (lines 2293-2314)

The staging directory is atomically renamed to the final install path via Os.rename():

// InstallPackageHelper.java:2293-2314
final File targetDir = resolveTargetDir(request.getInstallFlags(), request.getCodeFile());
final File afterCodeFile = PackageManagerServiceUtils.getNextCodePath(
        targetDir, parsedPackage.getPackageName());
makeDirRecursive(afterCodeFile.getParentFile(), 0771);
Os.rename(beforeCodeFile.getAbsolutePath(), afterCodeFile.getAbsolutePath());

This is an atomic operation: the entire vmdl<sessionId>.tmp/ directory becomes ~~<random>/<packageName>-<random>/ in a single filesystem rename.

10.3 Native Library Extraction

Source: PackageAbiHelperImpl.java - derivePackageAbi() (line 349)

For cluster installs (split APKs), native libraries are extracted into ISA-specific subdirectories:

// PackageAbiHelperImpl.java:206-218
// Cluster install
nativeLibraryRootDir = new File(codeFile, LIB_DIR_NAME).getAbsolutePath();
nativeLibraryRootRequiresIsa = true;
nativeLibraryDir = new File(nativeLibraryRootDir,
        getPrimaryInstructionSet(abis)).getAbsolutePath();

The actual extraction is performed by NativeLibraryHelper (NativeLibraryHelper.java):

The directory constants are defined as:

// NativeLibraryHelper.java:67-68
public static final String LIB_DIR_NAME = "lib";
public static final String LIB64_DIR_NAME = "lib64";

For multi-arch apps, both 32-bit and 64-bit libraries are extracted into separate ISA-specific subdirectories (e.g., lib/arm64/, lib/arm/).

10.4 DEX Optimization Output

Source: DexOptHelper.java - dexoptPackageUsingArtService() (line 350)

After installation, DEX bytecode is ahead-of-time compiled via the ART Service:

// DexOptHelper.java:350-382
DexoptParams params = getDexoptParamsByInstallRequest(installRequest);
return getArtManagerLocal().dexoptPackage(snapshot, ps.getPackageName(), params);

The ART daemon (artd) produces .odex and .vdex files. Their location is determined by AidlUtils.buildArtifactsPath() (AidlUtils.java:36):

The oat/ directory and its ISA subdirectories are created by Installer.createOatDirs() (Installer.java:594), which delegates to installd:

// Installer.java:594-603
public void createOatDirs(String packageName, String oatDir, List<String> oatSubDirs) {
    mInstalld.createOatDirs(packageName, oatDir, oatSubDirs);
}

During partial (inherit) installs, oat directories are pre-created for hard linking existing artifacts (PackageInstallerSession.java:3874).

10.5 Per-User Data Directories

Each installed package gets credential-encrypted (CE) and device-encrypted (DE) data directories per user:

/data/user/<userId>/<packageName>/          # CE storage (available after user unlock)
/data/user_de/<userId>/<packageName>/       # DE storage (available at boot)

Source: Environment.java (lines 92, 100):

public static final String DIR_USER_CE = "user";       // /data/user/<userId>/
public static final String DIR_USER_DE = "user_de";    // /data/user_de/<userId>/

These directories are created by AppDataHelper.prepareAppData() (AppDataHelper.java:215), which calls through to installd via Installer.createAppData(). The CE/DE data directory inodes are stored in PackageSetting for quick access.

User storage directories are first set up by UserDataPreparer.prepareUserData() (UserDataPreparer.java:72) when a user is created, and per-app directories are created within them during package installation.

10.6 Package Metadata Persistence

Split APK metadata is persisted across reboots in /data/system/packages.xml.

Source: Settings.java (line 746):

mSettingsFilename = new File(mSystemDir, "packages.xml");

What Is Stored

Settings.writePackageLPr() (line 3258) serializes each package with these key attributes:

Split-specific metadata is written by writeSplitVersionsLPr() (line 4640):

// Settings.java:4640-4654
private void writeSplitVersionsLPr(TypedXmlSerializer serializer,
        String[] splitNames, int[] splitRevisionCodes) throws IOException {
    for (int i = 0; i < libLength; i++) {
        serializer.startTag(null, TAG_SPLIT_VERSION);
        serializer.attribute(null, ATTR_NAME, splitNames[i]);
        serializer.attributeInt(null, ATTR_VERSION, splitRevisionCodes[i]);
        serializer.endTag(null, TAG_SPLIT_VERSION);
    }
}

Boot-Time Reconstruction

On boot, the system reads codePath from packages.xml, then re-parses the APK cluster directory using ApkLiteParseUtils.parseClusterPackageLite() to discover base.apk and all split_*.apk files. Split names, code paths, dependencies, and revision codes are all reconstructed from the on-disk APK manifests. readSplitVersionsLPw() (line 4612) reads persisted split revision codes to verify consistency.

10.7 ApplicationInfo Fields for Splits

Source: ApplicationInfo.java

10.8 Complete Installation Storage Overview

flowchart TB
    subgraph "Installation Storage"
        subgraph "Code Storage /data/app/"
            A["~~<random>/com.example.app-<random>/"]
            A --> B["base.apk"]
            A --> C["split_featureA.apk"]
            A --> D["split_config.xxhdpi.apk"]
            A --> E["lib/arm64/*.so"]
            A --> F["oat/arm64/*.odex, *.vdex"]
        end

        subgraph "User Data /data/user/"
            G["<userId>/com.example.app/"]
            G --> H["CE: databases, shared_prefs, files"]
        end

        subgraph "Device-Encrypted /data/user_de/"
            I["<userId>/com.example.app/"]
            I --> J["DE: available at boot before unlock"]
        end

        subgraph "System Metadata /data/system/"
            K["packages.xml"]
            K --> L["codePath, splitNames, splitRevisionCodes"]
        end
    end

11. Key Source Files Reference

Parsing Layer

Asset Loading Layer

Installation Layer

Runtime Layer

Report generated from AOSP source analysis. All file paths and line numbers reference the AOSP main branch.

I. The Big Picture

1. The shift to task delegation

The Android Developers Blog describes the change:

“User expectations for AI on their devices are fundamentally shifting how they interact with their apps.”

The traditional model – users manually opening apps, navigating UIs, completing tasks step by step – is giving way to task delegation. Users tell an AI agent what they want (“order my usual pizza”, “coordinate a rideshare with coworkers”), and the agent handles the multi-step workflow across apps.

What matters is no longer “app opens” but “task completion.” Android now has OS-level support for AI agents through two frameworks:

• AppFunctions – structured, API-based integration where apps explicitly expose capabilities
• ComputerControl – UI automation that works with any app, unmodified

flowchart TD
    subgraph "Traditional Model"
        U1[User] --> A1[Open App A]
        A1 --> A2[Navigate UI]
        A2 --> A3[Perform Action]
        A3 --> A4[Open App B]
        A4 --> A5[Navigate UI]
        A5 --> A6[Perform Action]
    end

    subgraph "Intelligent OS Model"
        U2[User] --> AI[AI Agent<br/>e.g. Gemini]
        AI --> AF[AppFunctions<br/>Structured Path]
        AI --> CC[ComputerControl<br/>UI Automation Path]
        AF --> T1[Task Completed<br/>in App A]
        CC --> T2[Task Completed<br/>in App B]
    end

2. Android’s Dual-Path Agent Architecture

Android gives AI agents two independent pathways to interact with apps. They share no code (zero cross-references in the codebase) but serve the same goal.

graph TB
    Agent["AI Agent<br/>(e.g. Gemini)"]

    subgraph AppFunctions["AppFunctions (Structured Path)"]
        AF_API["AppFunctionManager<br/>executeAppFunction()"]
        AF_SVC["AppFunctionManagerService<br/>(System Server)"]
        AF_APP["Target App's<br/>AppFunctionService"]
        AF_API --> AF_SVC
        AF_SVC --> AF_APP
    end

    subgraph ComputerControl["ComputerControl (UI Automation Path)"]
        CC_API["ComputerControlExtensions<br/>requestSession()"]
        CC_SVC["VirtualDeviceManagerService<br/>(System Server)"]
        CC_VD["VirtualDevice<br/>+ Virtual Display<br/>+ Input Devices"]
        CC_API --> CC_SVC
        CC_SVC --> CC_VD
    end

    Agent --> AppFunctions
    Agent --> ComputerControl

    style AppFunctions fill:#e8f5e9
    style ComputerControl fill:#e3f2fd

The blog describes this as:

• AppFunctions: “Allows apps to expose data and functionality directly to AI agents and assistants” – self-describing functions that agents discover and execute, like an on-device MCP.
• ComputerControl (the blog’s “UI automation framework”): “The platform doing the heavy lifting, so developers can get agentic reach with zero code” – generic task execution on any installed app with user transparency built in.

II. AppFunctions – Structured Intelligence

3. AppFunctions Overview

The blog introduces AppFunctions with a real-world example: on the Galaxy S26, a user asks Gemini “Show me pictures of my cat from Samsung Gallery.” The AI identifies the appropriate AppFunction, retrieves photos, and returns results within the Gemini interface – without the user ever opening the Gallery app.

AppFunctions (android.app.appfunctions) lets apps expose self-describing functions that AI agents discover via AppSearch and execute programmatically. Architecturally similar to MCP (Model Context Protocol), but runs entirely on-device.

sequenceDiagram
    participant User
    participant Agent as AI Agent (Gemini)
    participant AFM as AppFunctionManager
    participant Server as System Server<br/>(AppFunctionManagerServiceImpl)
    participant Target as Target App<br/>(AppFunctionService)

    User->>Agent: "Show me cat photos from Gallery"
    Agent->>Agent: Identify function via AppSearch
    Agent->>AFM: executeAppFunction(request)
    AFM->>Server: IAppFunctionManager.executeAppFunction()
    Server->>Server: Validate caller, permissions,<br/>access grants, enterprise policy,<br/>function enabled state
    Server->>Target: Bind & call IAppFunctionService.executeAppFunction()
    Target->>Target: onExecuteFunction()
    Target-->>Server: ExecuteAppFunctionResponse<br/>(+ optional URI grants)
    Server-->>AFM: Response callback
    AFM-->>Agent: Result (GenericDocument)
    Agent-->>User: Display cat photos

4. AppFunctions Core API

Entry Point: AppFunctionManager

The main client-facing API, registered as Context.APP_FUNCTION_SERVICE:

How Apps Expose Functions: AppFunctionService

Apps extend this abstract service to expose their functions:

classDiagram
    class AppFunctionService {
        <<abstract>>
        +onExecuteFunction(request, callingPackage, signingInfo, signal, receiver)*
        +createBinder(context, onExecuteFunction)$ Binder
    }

    class ExecuteAppFunctionRequest {
        +getTargetPackageName() String
        +getFunctionIdentifier() String
        +getParameters() GenericDocument
        +getExtras() Bundle
        +getAttribution() AppFunctionAttribution
    }

    class ExecuteAppFunctionResponse {
        +getResultDocument() GenericDocument
        +getExtras() Bundle
        +getUriGrants() List~AppFunctionUriGrant~
    }

    class AppFunctionException {
        +ERROR_DENIED = 1000
        +ERROR_INVALID_ARGUMENT = 1001
        +ERROR_DISABLED = 1002
        +ERROR_FUNCTION_NOT_FOUND = 1003
        +ERROR_SYSTEM_ERROR = 2000
        +ERROR_CANCELLED = 2001
        +ERROR_ENTERPRISE_POLICY_DISALLOWED = 2002
        +ERROR_APP_UNKNOWN_ERROR = 3000
    }

    class AppFunctionAttribution {
        +getInteractionType() int
        +getThreadId() String
        +getInteractionUri() Uri
    }

    AppFunctionService ..> ExecuteAppFunctionRequest : receives
    AppFunctionService ..> ExecuteAppFunctionResponse : returns
    AppFunctionService ..> AppFunctionException : throws
    ExecuteAppFunctionRequest --> AppFunctionAttribution : contains

Manifest declaration (required by target apps):

<service android:name=".MyAppFunctionService"
         android:permission="android.permission.BIND_APP_FUNCTION_SERVICE">
    <intent-filter>
        <action android:name="android.app.appfunctions.AppFunctionService"/>
    </intent-filter>
</service>

AIDL Interfaces

5. AppFunctions Server-Side Implementation

Core Service Architecture

graph TB
    subgraph SystemServer["System Server"]
        AFS["AppFunctionManagerService<br/>(SystemService wrapper)"]
        AFSI["AppFunctionManagerServiceImpl<br/>(~1220 lines, extends IAppFunctionManager.Stub)"]
        CV["CallerValidatorImpl"]
        RSC["RemoteServiceCallerImpl"]
        MSA["MetadataSyncAdapter"]
        AALS["AppFunctionAgentAllowlistStorage"]
        AH["MultiUserAppFunctionAccessHistory"]
        PM["AppFunctionPackageMonitor"]

        AFS --> AFSI
        AFSI --> CV
        AFSI --> RSC
        AFSI --> MSA
        AFSI --> AALS
        AFSI --> AH
        AFSI --> PM
    end

    subgraph Permission["Permission Service"]
        AAS["AppFunctionAccessService"]
        AAP["AppIdAppFunctionAccessPolicy"]
        APG["AppFunctionAccessPregrant"]

        AAS --> AAP
        AAS --> APG
    end

    AFSI --> AAS

Execution Pipeline

The executeAppFunction() method in AppFunctionManagerServiceImpl follows this pipeline:

flowchart TD
    A[executeAppFunction called] --> B[Validate caller identity<br/>UID matches claimed package]
    B --> C[Verify target user handle<br/>cross-user permissions]
    C --> D[Submit to THREAD_POOL_EXECUTOR]
    D --> E[Check enterprise policy<br/>DevicePolicyManager.getAppFunctionsPolicy]
    E --> F{Enterprise<br/>allowed?}
    F -->|No| G[ERROR_ENTERPRISE_POLICY_DISALLOWED]
    F -->|Yes| H[Verify execution permission<br/>EXECUTE_APP_FUNCTIONS + access grants]
    H --> I{Permission<br/>granted?}
    I -->|No| J[ERROR_DENIED]
    I -->|Yes| K[Check function enabled<br/>via AppSearch runtime metadata]
    K --> L{Enabled?}
    L -->|No| M[ERROR_DISABLED]
    L -->|Yes| N[Resolve AppFunctionService<br/>in target package]
    N --> O{Service<br/>found?}
    O -->|No| P[ERROR_SYSTEM_ERROR]
    O -->|Yes| Q[Grant implicit visibility<br/>target sees caller package]
    Q --> R[Bind to target service<br/>5s cancellation timeout]
    R --> S[Call IAppFunctionService.executeAppFunction]
    S --> T[Return response to caller]
    T --> U[Record access history<br/>in SQLite audit trail]

Remote Service Calling

RemoteServiceCallerImpl manages the one-off service connection:

• Binds to target’s AppFunctionService using bindServiceAsUser()
• Sets up cancellation signal with configurable timeout (default 5 seconds)
• Links to caller’s binder death for auto-cancel if caller dies
• Unbinds after completion, cancellation timeout, or service disconnect

6. AppFunctions Discovery System

Functions are discovered through a dual-metadata system in AppSearch:

graph LR
    subgraph AppsDB["AppSearch: apps-db (Static)"]
        SM["AppFunctionStaticMetadata<br/>- functionId<br/>- packageName<br/>- parameter schema<br/>- return type schema<br/>- enabledByDefault"]
    end

    subgraph FunctionsDB["AppSearch: appfunctions-db (Runtime)"]
        RM["AppFunctionRuntimeMetadata<br/>- functionId<br/>- packageName<br/>- enabled state override"]
    end

    SM ---|"Joined via<br/>qualifiedId"| RM

    PackageInstall["Package Install/Update"] -->|"System indexes"| SM
    StateChange["setAppFunctionEnabled()"] -->|"System writes"| RM

    Agent["AI Agent"] -->|"GlobalSearchSession<br/>query"| SM
    Agent -->|"Join query"| RM

Metadata synchronization (MetadataSyncAdapter):

1. Triggered on user unlock and AppSearch observer changes
2. Queries both static and runtime AppSearch databases
3. Computes diff (added/removed functions)
4. Creates runtime metadata for new functions, removes for deleted ones
5. Sets AppSearch schema visibility per-package using signing certificates and EXECUTE_APP_FUNCTIONS permission

Effective enabled state: Runtime override takes precedence over static enabledByDefault.

7. AppFunctions Access Control

Three-Layer Agent Allowlisting

graph TD
    subgraph Layer1["Layer 1: System Hardcoded"]
        SH["com.android.shell"]
    end

    subgraph Layer2["Layer 2: DeviceConfig (Updatable)"]
        DC["machine_learning namespace<br/>allowlisted_app_functions_agents<br/>Format: packageName:certHex"]
    end

    subgraph Layer3["Layer 3: ADB Secure Setting"]
        ADB["Settings.Secure<br/>APP_FUNCTION_ADDITIONAL_AGENT_ALLOWLIST"]
    end

    Layer1 --> Merge["Merged AgentAllowlist<br/>(ArraySet of SignedPackage)"]
    Layer2 --> Merge
    Layer3 --> Merge

    Merge --> Policy["AppIdAppFunctionAccessPolicy"]

    Storage["AppFunctionAgentAllowlistStorage<br/>/data/system/appfunctions/agent_allowlist.txt<br/>(AtomicFile, crash-safe)"]
    DC -.->|"Persisted to"| Storage

Access Flag Bitmask System

Per agent-target pair, access is tracked via bitmask flags:

Priority: USER flags override OTHER flags. If no DENIED flags present, PREGRANTED means granted.

Audit Trail

Every execution is recorded in a per-user SQLite database (appfunction_access.db):

Cleanup: Scheduled every 24 hours, retaining 7 days of history.

8. AppFunctions Feature Flags

III. ComputerControl – Universal UI Automation

9. ComputerControl Overview

The blog introduces the second pathway:

“A UI automation framework for AI agents and assistants to intelligently execute generic tasks on users’ installed apps, with user transparency and control built in.”

“The platform doing the heavy lifting, so developers can get agentic reach with zero code.”

ComputerControl (android.companion.virtual.computercontrol) allows programmatic automation of Android apps running on a trusted virtual display. Built on the VirtualDeviceManager (VDM) infrastructure, it lets an authorized agent:

• Launch applications on an isolated virtual display
• Inject input (taps, swipes, long presses, key events, text)
• Capture screenshots of the display content
• Mirror the display for user “live view” with interactive touch forwarding
• Monitor UI stability (detect when the display has settled)
• Hand over automated apps back to the user’s default display

User-facing aspects from the blog:

• Users monitor progress via “notifications or ‘live view’“ (implemented by MirrorView + InteractiveMirrorDisplay)
• Users “can switch to manual control at any point” (implemented by handOverApplications() and MirrorView.setInteractive(true))
• Alerts precede “sensitive tasks, such as making a purchase”
• Currently in early preview on Galaxy S26 series and select Pixel 10 devices

10. ComputerControl Architecture

Layered Architecture

graph TB
    subgraph Client["Client Application (Agent)"]
        CCE["ComputerControlExtensions<br/>(Entry point / Factory)"]
        CCS_EXT["ComputerControlSession<br/>(Extension SDK)"]
        MV["MirrorView<br/>(TextureView + Overlay)"]
        IM["InteractiveMirror"]
    end

    subgraph PlatformAPI["Core Platform API"]
        VDM["VirtualDeviceManager<br/>requestComputerControlSession()"]
        CCS["ComputerControlSession"]
        CCSP["ComputerControlSessionParams"]
        IMD["InteractiveMirrorDisplay"]
    end

    subgraph SystemServer["System Server"]
        VDMS["VirtualDeviceManagerService"]
        CCSP_P["ComputerControlSessionProcessor<br/>(consent, limits, validation)"]
        CCSI["ComputerControlSessionImpl<br/>(777 lines, core binder)"]
        SC["StabilityCalculator"]
        IMDI["InteractiveMirrorDisplayImpl"]
        APR["AutomatedPackagesRepository"]
    end

    subgraph VirtualDevice["Virtual Device"]
        VD["VirtualDevice"]
        TD["Trusted VirtualDisplay<br/>(animations disabled, IME hidden)"]
        TS["VirtualTouchscreen<br/>(0xCC03)"]
        KB["VirtualKeyboard<br/>(0xCC02)"]
        DP["VirtualDpad<br/>(0xCC01)"]
    end

    CCE --> VDM
    CCS_EXT --> CCS
    MV --> IM
    IM --> IMD

    VDM -->|"Binder IPC"| VDMS
    VDMS --> CCSP_P
    CCSP_P -->|"creates"| CCSI
    CCSI --> SC
    CCSI --> IMDI
    VDMS --> APR

    CCSI --> VD
    VD --> TD
    VD --> TS
    VD --> KB
    VD --> DP

    style Client fill:#e3f2fd
    style SystemServer fill:#fff3e0
    style VirtualDevice fill:#f3e5f5

Component Responsibilities

Client-Side (Extension SDK Library)

Server-Side (System Services)

Public API Surface

Entry point: VirtualDeviceManager.requestComputerControlSession() (requires ACCESS_COMPUTER_CONTROL)

Session configuration (ComputerControlSessionParams):

Session operations (ComputerControlSession):

AIDL IPC Interfaces

11. Session Lifecycle

sequenceDiagram
    participant Agent as Agent App
    participant Server as System Server<br/>(SessionProcessor)
    participant User as User

    Agent->>Server: requestComputerControlSession(params)
    Server->>Server: Validate params<br/>(unique name, valid targets)
    Server->>Server: Check AppOps<br/>OP_COMPUTER_CONTROL

    alt Consent needed
        Server-->>Agent: onSessionPending(PendingIntent)
        Agent->>User: Launch consent dialog
        User->>User: Allow / Don't Allow / Always Allow
        alt Denied
            User-->>Server: RESULT_CANCELED
            Server-->>Agent: onSessionCreationFailed(PERMISSION_DENIED)
        else Approved
            User-->>Server: RESULT_OK
        end
    end

    Server->>Server: Check device not locked
    Server->>Server: Check session limit (< 5)
    Server->>Server: Create VirtualDevice
    Server->>Server: Create trusted VirtualDisplay
    Server->>Server: Create input devices<br/>(dpad, keyboard, touchscreen)
    Server->>Server: Disable animations
    Server->>Server: Set IME policy HIDE

    Server-->>Agent: onSessionCreated(displayId, session)

    loop Active Session
        Agent->>Server: tap / swipe / longPress
        Agent->>Server: insertText / performAction
        Agent->>Server: launchApplication
        Agent->>Server: getScreenshot
        Server-->>Agent: onSessionStable()
    end

    Agent->>Server: close()
    Server-->>Agent: onSessionClosed()

Error Conditions

Auto-Close Triggers

• Agent app process dies (via DeathRecipient / binder death)
• Explicit close() call
• System decides to terminate the session

Server-Side Session Creation

ComputerControlSessionProcessor:

• Dedicated ServiceThread at THREAD_PRIORITY_FOREGROUND (lazy-initialized)
• Maximum 5 concurrent sessions (MAXIMUM_CONCURRENT_SESSIONS)
• Session name uniqueness enforced per-package
• Consent integration via AppOpsManager.OP_COMPUTER_CONTROL

ComputerControlSessionImpl (777 lines):

• Creates VirtualDeviceParams with DEVICE_POLICY_CUSTOM for activity blocking
• Trusted virtual display with focus-stealing disabled
• Three virtual input devices: Dpad (0xCC01), Keyboard (0xCC02), Touchscreen (0xCC03)
• Activity policy: strict mode (only target packages) or legacy mode (all except PermissionController)

12. Input Handling

Input Device Architecture

graph TD
    CCSI["ComputerControlSessionImpl"]

    CCSI --> Dpad["VirtualDpad (0xCC01)<br/>DPAD_*, BACK, HOME,<br/>ENTER, TAB"]
    CCSI --> KB["VirtualKeyboard (0xCC02)<br/>Character key events"]
    CCSI --> TS["VirtualTouchscreen (0xCC03)<br/>Touch input"]

    tap["tap(x, y)"] --> TS
    swipe["swipe(from, to)"] --> TS
    longPress["longPress(x, y)"] --> TS
    sendTouch["sendTouchEvent()"] --> TS
    sendKey["sendKeyEvent()"] -->|"DPAD keycodes"| Dpad
    sendKey -->|"Other keycodes"| KB
    performAction["performAction(GO_BACK)"] --> Dpad

High-Level Gesture Implementation

Swipe interpolation: Uses Math.sin(fraction * PI/2) for natural-feeling sine easing. Dispatched via ScheduledExecutorService with 50ms delays.

Extension SDK Input Types

• TouchEvent: Immutable, builder pattern. pointerId (0-15), toolType (FINGER/PALM), action (DOWN/UP/MOVE/CANCEL), x, y, pressure (0-255), majorAxisSize. ACTION_CANCEL must pair with TOOL_TYPE_PALM.
• KeyEvent: Immutable, builder pattern. keyCode, action (DOWN/UP), eventTimeNanos.

13. Display Mirroring and Live View

The blog highlights that users can “monitor a task’s progress via notifications or ‘live view’” and “switch to manual control at any point.” This is implemented through the interactive mirror display system.

graph TB
    subgraph SessionDisplay["Session Virtual Display (Trusted)"]
        Apps["Automated Apps<br/>Running Here"]
    end

    subgraph MirrorSystem["Interactive Mirror System"]
        IMDI["InteractiveMirrorDisplayImpl"]
        MirrorDisplay["Mirror VirtualDisplay<br/>(AUTO_MIRROR flag)"]
        MirrorTS["Mirror VirtualTouchscreen"]
        ClientSurface["Client Surface"]
    end

    subgraph ClientView["Client-Side MirrorView"]
        TV["TextureView<br/>(renders mirror content)"]
        OV["Overlay View<br/>(touch indicators)"]
        MH["MirrorHelper<br/>(lifecycle management)"]
    end

    SessionDisplay -->|"AUTO_MIRROR"| MirrorDisplay
    IMDI --> MirrorDisplay
    IMDI --> MirrorTS
    MirrorDisplay --> ClientSurface
    ClientSurface --> TV

    TV --> MH
    MH -->|"Touch events<br/>(when interactive)"| MirrorTS
    OV -->|"Red circles<br/>with fade animation"| TV

Server-Side: InteractiveMirrorDisplayImpl

• Creates a mirror virtual display with AUTO_MIRROR flag linked to session display
• Associates a virtual touchscreen with the mirror display
• resize(w, h): Resizes display, destroys and recreates touchscreen (no touchscreen resize API)
• sendTouchEvent(): Forwards to mirror touchscreen

Client-Side: MirrorView

A ready-to-use FrameLayout providing the “live view” experience:

• setComputerControlSession(session) – Binds/unbinds session for mirroring
• setInteractive(boolean) – Enables touch-to-control forwarding (manual takeover)
• setShowTouches(boolean) – Shows/hides touch indicator dots
• Handles coordinate translation with letterboxing/pillarboxing

14. Stability Tracking

ComputerControl provides two stability mechanisms to help agents wait for UI to settle:

Platform-Level StabilityListener (Current)

Server-side StabilityCalculator uses timeout-based heuristics:

stateDiagram-v2
    [*] --> Waiting: Input event occurs

    Waiting --> Stable: Timeout elapsed, no new input
    Waiting --> Waiting: New input event, timer reset
    Stable --> [*]: onSessionStable() fired

    note right of Waiting
        Timeouts by event type:
        - Non-continuous (tap, text): 2000ms
        - Continuous (swipe, long press): 2500ms
        - App launch: 3000ms
        - Interaction failed: Immediate
    end note

• Registered via setStabilityListener(executor, listener)
• Only one listener per session
• Each new input event resets the timer
• Marked as temporary implementation (TODO b/428957982)

Deprecated StabilityHintCallback (Extension SDK)

• Uses AccessibilityDisplayProxy monitoring accessibility events on the virtual display
• EventIdleTracker with 500ms idle timeout
• One-shot callback pattern (must be re-registered)

15. IME and Text Input Integration

ComputerControl bypasses the normal on-screen keyboard for programmatic text entry:

sequenceDiagram
    participant Agent as Agent App
    participant Session as ComputerControlSessionImpl
    participant IMMS as InputMethodManagerService
    participant TextField as Active Text Field<br/>(in automated app)

    Note over Session: Display IME policy = HIDE<br/>(no on-screen keyboard)

    Agent->>Session: insertText("hello", false, true)

    alt computerControlTyping flag ON
        Session->>IMMS: getComputerControlInputConnection(userId, displayId)
        IMMS-->>Session: IRemoteComputerControlInputConnection
        Session->>TextField: commitText("hello") via InputConnection
        Session->>Session: Send ENTER key (commit=true)
    else Legacy path (flag OFF)
        Session->>Session: Convert text to KeyEvent[] via KeyCharacterMap
        Session->>Session: Send individual key events with 10ms delays
    end

How the InputConnection is established:

1. When an app gains input focus on a CC display, InputMethodManagerService.startInputOrWindowGainedFocus() stores the IRemoteComputerControlInputConnection in UserData.mComputerControlInputConnectionMap keyed by displayId
2. The session impl retrieves it via InputMethodManagerInternal.getComputerControlInputConnection()
3. When the client disconnects, the entry is removed

16. Automated Package Tracking

The blog mentions users can “monitor a task’s progress via notifications.” This is powered by AutomatedPackagesRepository, which allows launchers (ROLE_HOME apps) to display indicators for automated packages.

flowchart TD
    subgraph CCSession["CC Session<br/>(Virtual Display)"]
        RunningApps["Running Apps<br/>(on CC display)"]
    end

    VDMS["VirtualDeviceManagerService<br/>onRunningAppsChanged()"]
    APR["AutomatedPackagesRepository"]
    Launcher["Launcher App<br/>(ROLE_HOME)"]
    Warning["AutomatedAppLaunchWarningActivity"]

    RunningApps -->|"App changes"| VDMS
    VDMS -->|"update(deviceId, packages)"| APR
    APR -->|"onAutomatedPackagesChanged()"| Launcher

    APR -->|"Launch interception"| Warning
    Warning -->|"Wait"| Dismiss["Dismiss (don't launch)"]
    Warning -->|"Stop"| Close["Close virtual device"]

Data model:

• mAutomatedPackages: ownerPackage -> userId -> Set<packageNames> (aggregated across devices)
• mDevicePackages: deviceId -> userId -> Set<packageNames> (per-device)
• mInterceptedLaunches: Tracks packages where user already approved automated launch

17. ComputerControl Security Model

The blog emphasizes “privacy and security at their core.” ComputerControl has multiple security layers:

Permission and Consent

flowchart TD
    Agent["Agent App"] --> Perm{"Has ACCESS_COMPUTER_CONTROL?<br/>(internal + knownSigner)"}
    Perm -->|No| Blocked["Cannot create sessions"]
    Perm -->|Yes| Consent{"AppOps OP_COMPUTER_CONTROL?"}
    Consent -->|MODE_ALLOWED| Create["Create session"]
    Consent -->|Not set| Dialog["Show consent dialog"]
    Dialog --> Allow["Allow (one-time)"]
    Dialog --> Deny["Don't Allow"]
    Dialog --> Always["Always Allow<br/>(sets MODE_ALLOWED)"]
    Allow --> Create
    Deny --> Failed["ERROR_PERMISSION_DENIED"]
    Always --> Create

Anti-Tampering Measures

UI Components (VirtualDeviceManager Package)

18. ComputerControl Feature Flags

All flags in frameworks/base/core/java/android/companion/virtual/flags/flags.aconfig:

IV. Comparative Analysis

19. AppFunctions vs ComputerControl

graph LR
    subgraph AF["AppFunctions"]
        AF1["Structured API"]
        AF2["App opt-in required"]
        AF3["Fast & reliable"]
        AF4["Type-safe data"]
        AF5["Background execution"]
        AF6["Request/response"]
    end

    subgraph CC["ComputerControl"]
        CC1["UI Automation"]
        CC2["Works with any app"]
        CC3["Visual context"]
        CC4["Pixel-based data"]
        CC5["Visible via live view"]
        CC6["Session-based"]
    end

    Agent["AI Agent"] --> AF
    Agent --> CC

    AF -.->|"Preferred when<br/>app supports it"| Result["Task Completed"]
    CC -.->|"Universal fallback"| Result

When an AI Agent Would Use Each

20. Security Model Comparison

graph TB
    subgraph AF_Security["AppFunctions Security"]
        AF_P["Permission:<br/>EXECUTE_APP_FUNCTIONS<br/>(normal + allowlist)"]
        AF_A["Agent Gating:<br/>3-layer allowlist<br/>(system + DeviceConfig + ADB)"]
        AF_C["Consent:<br/>Access request UI<br/>per agent-target pair"]
        AF_AU["Audit:<br/>SQLite access history<br/>with attribution"]
        AF_E["Enterprise:<br/>DevicePolicyManager<br/>AppFunctionsPolicy"]
        AF_S["Scope:<br/>Only declared<br/>function results"]
    end

    subgraph CC_Security["ComputerControl Security"]
        CC_P["Permission:<br/>ACCESS_COMPUTER_CONTROL<br/>(internal + knownSigner)"]
        CC_A["Agent Gating:<br/>Known signer<br/>certificates"]
        CC_C["Consent:<br/>Per-session dialog<br/>(Allow/Don't Allow/Always)"]
        CC_AU["Audit:<br/>AutomatedPackagesRepository<br/>+ launcher notifications"]
        CC_E["Enterprise:<br/>No enterprise<br/>policy integration"]
        CC_S["Scope:<br/>Full display content<br/>(screenshots + input)"]
    end

ComputerControl has a stricter permission model (internal|knownSigner vs normal with allowlist) because it has broader access – it can see and interact with any UI content, whereas AppFunctions only exposes what apps explicitly declare.

21. The Incremental Adoption Strategy

The blog outlines a roadmap: Android 17 will “broaden these capabilities to reach even more users, developers, and device manufacturers.” The dual-path architecture makes incremental adoption possible:

timeline
    title Android AI Agent Ecosystem Evolution
    section Phase 1 - Launch
        ComputerControl provides universal coverage : Works with any app unmodified
        AppFunctions adopted by key partners : Samsung Gallery, Calendar, Notes
        Limited rollout : Galaxy S26, select Pixel 10
    section Phase 2 - Expansion (Android 17)
        More apps adopt AppFunctions : Higher quality agent experiences
        ComputerControl coverage expands : More device manufacturers
        Developer tools and documentation : AppFunctions Jetpack library
    section Phase 3 - Maturity
        AppFunctions becomes primary path : Most apps expose structured functions
        ComputerControl remains universal fallback : Legacy apps, complex workflows
        Full ecosystem : User trust established via transparency

The ecosystem can start with ComputerControl for broad “zero code” coverage, then shift to AppFunctions as more apps integrate. In the blog’s framing:

• AppFunctions = “expose data and functionality directly” (preferred path)
• ComputerControl = “platform doing the heavy lifting… zero code” (universal fallback)

Both give users control over what agents can do: AppFunctions via access management UI and audit trails, ComputerControl via consent dialogs, live view, and manual takeover.

V. Reverse Engineering Gemini’s ComputerControl Integration

22. APK Analysis Methodology

To verify whether Google’s Gemini assistant actually uses the AOSP ComputerControl APIs described in earlier sections, we performed static analysis on APK files downloaded from APKMirror:

Both target SDK 35 and compile against SDK 36 (Baklava). The analysis used aapt2 for manifest inspection, dexdump for DEX class/method enumeration, and strings for broad string-table sweeps across all DEX files.

23. Gemini Shell App – A Thin Launcher

The Gemini app (com.google.android.apps.bard) is not the actual Gemini runtime. It is a minimal launcher shell with only 6 real classes:

The manifest declares only three permissions (WAKE_LOCK, ACCESS_NETWORK_STATE, GET_PACKAGE_SIZE) and queries a single package: com.google.android.googlequicksearchbox. Its splits0.xml contains only language and density config splits — no on-demand feature modules.

Searching all 4,935 obfuscated classes across both DEX files turned up zero references to ComputerControlSession, VirtualDeviceManager, ACCESS_COMPUTER_CONTROL, AccessibilityService, or any UI automation APIs. The shell delegates everything to AGSA via signed deep-link intents.

24. AGSA – The Actual ComputerControl Consumer

AGSA is where the ComputerControl integration lives. Its manifest explicitly declares:

<uses-permission android:name="android.permission.ACCESS_COMPUTER_CONTROL" />
<uses-permission android:name="android.permission.EXECUTE_APP_FUNCTIONS" />

<uses-library
    android:name="com.android.extensions.computercontrol"
    android:required="false" />
<uses-library
    android:name="com.android.extensions.appfunctions"
    android:required="false" />

Both extension libraries are optional (required=false), so AGSA can install on devices where the platform extensions aren’t available yet. Other relevant permissions: SYSTEM_ALERT_WINDOW, FOREGROUND_SERVICE_MEDIA_PROJECTION, DETECT_SCREEN_CAPTURE, START_ACTIVITIES_FROM_BACKGROUND, and QUERY_ALL_PACKAGES.

Internally, the feature is codenamed “Bonobo” (log prefix #bnb#). It sits alongside other Gemini feature modes like FEATURE_MODE_DEEP_RESEARCH and FEATURE_MODE_IMAGE_GENERATION within the Robin assistant surface.

25. ComputerControl API Usage in AGSA

AGSA calls every major method of ComputerControlSession. The table below maps platform API methods (from Section 10) to their confirmed presence in AGSA’s DEX:

AGSA also references both the platform MirrorView (com.android.extensions.computercontrol.view.MirrorView) and its own thin subclass (com.google.android.libraries.computercontrol.view.MirrorView). The ComputerControlSession.Callback interface is implemented by cqmz, which handles onSessionCreated, onSessionCreationFailed, onSessionPending, and onSessionClosed.

26. Bonobo Agent Architecture

graph TB
    subgraph Server["Gemini Server"]
        GS["Gemini Model<br/>(screenshot analysis + action planning)"]
    end

    subgraph AGSA["AGSA (com.google.android.googlequicksearchbox)"]
        subgraph Robin["Robin Assistant Surface"]
            ROP["RobinOp Handler<br/>(classes.dex:aloz)"]
            ELIG["Bonobo Eligibility Checker<br/>(classes.dex:aiiy)"]
        end

        subgraph Orchestrator["Session Orchestrator (classes9.dex:aiku)"]
            SM["State Machine<br/>Running ↔ Blocked ↔ ControlledByUser → Stopped"]
            SC_L["Screenshot Capture"]
            ENC["BonoboImageEncrypter<br/>(classes9.dex:aiiz)"]
            STAB["Stability Checker<br/>(screenshot diff)"]
        end

        subgraph CCWrapper["CC SDK Wrapper (classes6.dex)"]
            EXT["ComputerControlExtensions Holder<br/>(cqna)"]
            CB["Session Callback<br/>(cqmz)"]
            SESS["Session Wrapper<br/>(cqnk)"]
        end

        subgraph UI["Bonobo UI (classes10.dex)"]
            MV["MirrorView<br/>(live screen mirror)"]
            FG["BonoboSessionForegroundService"]
            FRE["First Run Experience Dialog"]
            CONFIRM["Confirm Alert Dialog"]
        end
    end

    subgraph Platform["AOSP Platform"]
        CCE["ComputerControlExtensions"]
        CCS["ComputerControlSession"]
        VDM["VirtualDeviceManagerService"]
        VD["VirtualDevice + Display + Input"]
    end

    GS -->|"ProcessQuery stream<br/>(RobinOp instructions)"| ROP
    ROP --> ELIG
    ROP -->|"dispatch actions"| SM
    SM --> SC_L
    SC_L --> ENC
    ENC -->|"encrypted screenshots"| GS
    SM --> STAB
    SM -->|"tap/swipe/type/back"| SESS

    EXT -->|"getInstance()"| CCE
    CB -->|"onSessionCreated"| SESS
    SESS -->|"API calls"| CCS
    CCS --> VDM
    VDM --> VD
    SESS -->|"setComputerControlSession"| MV

    style Server fill:#fce4ec
    style Robin fill:#e3f2fd
    style Orchestrator fill:#e8f5e9
    style CCWrapper fill:#fff3e0
    style UI fill:#f3e5f5
    style Platform fill:#ede7f6

This is a server-driven agent loop. The Gemini server sends RobinOp instructions over a bidirectional ProcessQuery stream. AGSA captures encrypted screenshots and uploads them for server-side analysis, then executes the returned actions via ComputerControlSession.

27. Bonobo Agent Turn Cycle

sequenceDiagram
    participant GS as Gemini Server
    participant ROP as RobinOp Handler
    participant ORCH as Session Orchestrator
    participant CC as ComputerControlSession
    participant VD as Virtual Display

    Note over ROP,CC: Session Initialization
    ROP->>ORCH: StartBonoboSession(flowToken)
    ORCH->>CC: ComputerControlExtensions.getInstance()
    ORCH->>CC: requestComputerControlSession(params)
    CC-->>ORCH: onSessionCreated(session)
    ORCH->>CC: MirrorView.setComputerControlSession()

    loop Agent Turn Cycle
        Note over GS,VD: ROBIN_BONOBO_TURN_FLOW_START

        ORCH->>CC: getScreenshot()
        Note over GS,VD: SCREENSHOT_CAPTURE_START → SCREENSHOT_CAPTURE_END
        ORCH->>ORCH: Encrypt screenshot (BonoboImageEncrypter)
        ORCH->>GS: Upload encrypted screenshot
        Note over GS,VD: SCREENSHOT_UPLOAD_START → SCREENSHOT_UPLOAD_END

        GS->>GS: Analyze screenshot
        GS->>ROP: RobinOp (action instruction)

        ROP->>ORCH: Dispatch action

        alt TAP
            ORCH->>CC: tap(x, y)
        else SCROLL
            ORCH->>CC: swipe(fromX, fromY, toX, toY)
        else INSERT TEXT
            ORCH->>CC: insertText(text, replace, commit)
        else GO_BACK
            ORCH->>CC: performAction(ACTION_GO_BACK)
        else START
            ORCH->>CC: launchApplication(packageName)
        else HAND_OVER
            ORCH->>CC: handOverApplications()
        else WAIT
            ORCH->>ORCH: Pause execution
        end

        Note over GS,VD: ACTION_EXECUTION_START
        ORCH->>CC: setStabilityListener()
        CC-->>ORCH: onSessionStable()
        Note over GS,VD: PAGE_STABILIZATION_END

        Note over GS,VD: ROBIN_BONOBO_TURN_SUCCESS
    end

    alt User takes over
        Note over GS,VD: TURN_USER_TAKEOVER_RESPONSE_RECEIVED
        ORCH->>ORCH: State → ControlledByUser
    else Task complete
        Note over GS,VD: TURN_TASK_COMPLETED_RESPONSE_RECEIVED
        ORCH->>CC: close()
    else User stops
        Note over GS,VD: TURN_TASK_STOPPED_BY_USER
        ORCH->>CC: close()
    end

Each turn follows a fixed sequence tracked by instrumentation events:

28. Bonobo Session State Machine

stateDiagram-v2
    [*] --> StartBonoboSession: flowToken received

    StartBonoboSession --> Running: onSessionCreated
    StartBonoboSession --> Stopped: onSessionCreationFailed

    Running --> Running: execute turn cycle
    Running --> Blocked: waiting for user input
    Running --> ControlledByUser: user takes over
    Running --> Stopped: task complete / error

    Blocked --> Running: user clarification received
    Blocked --> Stopped: user stops task

    ControlledByUser --> Running: user returns control
    ControlledByUser --> Stopped: user ends session

    Stopped --> [*]

The session orchestrator (aiku) maintains this state machine with the following states, each holding a reference to the ComputerControlSession wrapper:

29. Supported Agent Actions

The RobinOp handler (aloz) dispatches the following actions received from the Gemini server:

30. Screenshot Encryption and Upload

Bonobo encrypts screenshots before uploading them to the Gemini server. The BonoboImageEncrypter class (aiiz in classes9.dex) processes raw screenshot bytes through an encryption method (a([B) -> [B) before transmission.

The orchestrator also does screenshot diff comparison for stability detection – comparing consecutive screenshots to determine when the UI has settled after an action, on top of the platform’s StabilityListener callback.

31. Device Eligibility and Feature Gating

Bonobo’s eligibility checker (aiiy) enforces multiple constraints:

"#bnb# Device is not eligible. Skip eligibility checks enabled %s,
 is Pixel 10+ %s, is Samsung S26 %s"

The ACCESS_COMPUTER_CONTROL permission has protection level internal|knownSigner in AOSP, with trusted certificates configured via config_accessComputerControlKnownSigners. The AOSP base leaves this array empty — OEMs must overlay it with specific signing certificate digests for their authorized agent apps. On Pixel devices, Google overlays this with AGSA’s signing certificate.

32. Bonobo UI Components

graph LR
    subgraph GeminiChat["Gemini Chat UI"]
        MSG["Chat Messages"]
        NARR["Action Narration<br/>(what the agent is doing)"]
        MV["MirrorView<br/>(live screen mirror)"]
        BTN["Action Buttons<br/>(Open App / View Live)"]
    end

    subgraph SystemUI["System UI"]
        FG["BonoboSessionForegroundService<br/>(persistent notification)"]
        NOTIF["Notification Actions<br/>(via TrampolineActivity)"]
    end

    subgraph Dialogs["Consent & Warnings"]
        FRE["First Run Experience<br/>(BonoboFreViewModel)"]
        CONFIRM["Confirmation Dialog<br/>(BonoboConfirmAlertDialog)"]
        MULTI["Multiple Session Dialog<br/>(BonoboMultipleSessionViewModel)"]
        NOTIF_REQ["Notification Permission<br/>(BonoboNotificationRequestViewModel)"]
    end

    MV -->|"setComputerControlSession()"| FG
    NOTIF -->|"BonoboNotificationActionTrampolineActivity"| GeminiChat

    style GeminiChat fill:#e3f2fd
    style SystemUI fill:#fff3e0
    style Dialogs fill:#fce4ec

The Bonobo UI is embedded within the Robin (Gemini) chat surface. The view binding class (aqki) reveals the layout structure: a MaterialToolbar header, a TextView for status/narration, a FrameLayout containing the MirrorView for live screen mirroring, and two MaterialButtons. A BonoboSessionForegroundService keeps the session alive with a persistent notification, and a BonoboNotificationActionTrampolineActivity handles notification action clicks to return the user to the session.

33. Dual-Path Integration: ComputerControl + AppFunctions

AGSA’s manifest declares both com.android.extensions.computercontrol and com.android.extensions.appfunctions libraries, along with both ACCESS_COMPUTER_CONTROL and EXECUTE_APP_FUNCTIONS permissions. This confirms the dual-path architecture from Section 2: Gemini uses AppFunctions for apps that expose function APIs, and falls back to ComputerControl’s UI automation for apps that don’t.

graph TB
    subgraph Gemini["Gemini Agent (AGSA)"]
        ROUTER["Action Router"]
    end

    subgraph Structured["Structured Path"]
        AF["AppFunctions SDK<br/>(com.android.extensions.appfunctions)"]
        PERM_AF["EXECUTE_APP_FUNCTIONS"]
    end

    subgraph Universal["Universal Path"]
        CC["ComputerControl SDK<br/>(com.android.extensions.computercontrol)"]
        PERM_CC["ACCESS_COMPUTER_CONTROL"]
    end

    subgraph Apps["Target Applications"]
        APP_AF["Apps with AppFunctions<br/>(structured API)"]
        APP_CC["Any App<br/>(UI-based automation)"]
    end

    ROUTER -->|"app exposes functions"| AF
    ROUTER -->|"generic UI task"| CC
    AF --> PERM_AF
    CC --> PERM_CC
    AF --> APP_AF
    CC --> APP_CC

    style Gemini fill:#e3f2fd
    style Structured fill:#e8f5e9
    style Universal fill:#fff3e0
    style Apps fill:#f3e5f5

34. Key Findings Summary

AGSA v17.9.53 uses the full AOSP ComputerControl API surface. Bonobo is a server-driven agent loop: the Gemini model analyzes encrypted screenshots, plans actions, and sends them as RobinOp instructions over a bidirectional stream. AGSA executes those actions through ComputerControlSession on an isolated virtual display, while the user can watch via MirrorView in the Gemini chat UI.

VI. Reference

35. Key Source File Reference

AppFunctions Core API (frameworks/base/core/java/android/app/appfunctions/)

AppFunctions Server (frameworks/base/services/appfunctions/java/.../appfunctions/)

AppFunctions Permission (frameworks/base/services/permission/java/.../appfunction/)

ComputerControl Extension SDK (frameworks/base/libs/computercontrol/)

ComputerControl Core API (frameworks/base/core/java/android/companion/virtual/computercontrol/)

ComputerControl Server (frameworks/base/services/companion/java/.../computercontrol/)

VirtualDevice Integration

InputMethod Integration

UI Components (frameworks/base/packages/VirtualDeviceManager/)

Feature Flags

I’m not a frontend engineer, and I wanted to replace the minima theme on my Jekyll blog with a custom one – no frontend experience required. I used Claude Code to build the entire theme in a single session.

What Was Done

Built a Complete Local Theme

Claude Code read the existing repository structure, fetched the reference design, and produced a full theme from scratch:

• 4 layouts: default.html, home.html, page.html, post.html
• 4 includes: head.html (meta, fonts, dark mode flash prevention), header.html (sticky nav, theme toggle), footer.html (social links), scripts.html (theme/nav/mermaid JS)
• 4 SCSS files: variables.scss (design tokens), base.scss (reset, CSS custom properties for light/dark themes), layout.scss (all components), syntax.scss (code highlighting for both themes)

Design: Inter font, JetBrains Mono for code, purple accent (#6041ed), CSS custom properties for theme switching, responsive down to mobile.

Removed All External Theme Dependencies

Dropped the minima gem from Gemfile, removed theme: minima from _config.yml, and traced every site.minima.* reference across all templates to replace them with direct config paths.

Made Mermaid Diagrams Built-in

Before: required mermaid: true in front matter and <div class="mermaid"> HTML blocks.

After: mermaid loads automatically on every page. Standard ` ```mermaid ` fenced code blocks work out of the box – same syntax as VS Code markdown preview. JavaScript converts Jekyll’s rendered <pre><code class="language-mermaid"> elements into mermaid divs at runtime. All existing posts were refactored to the new format.

Replaced an External Plugin with a Local One

The jekyll-remote-include gem (pulled from GitHub) was replaced with a 38-line local plugin in _plugins/remote_include.rb. The local version adds proper HTTP redirect handling and error reporting. One fewer external dependency.

Homepage with Author Info and Formatted Post Excerpts

Extracted author bio and project links from the about page into a hero section on the homepage. Post excerpts render full HTML content (headings, code blocks, lists) inside a CSS height-clamp with a fade-out gradient, preserving the original article formatting.

Applied 7 Code Review Suggestions from GitHub Copilot

Gave Claude Code the PR URL. It fetched all Copilot review comments and applied them:

1. Fixed typo: giscuss to giscus
2. Mermaid dark mode: initializes with matching theme based on site preference
3. Giscus theme sync: sends postMessage to iframe on theme toggle
4. Google Analytics: gated behind jekyll.environment == 'production', measurement ID moved to _config.yml
5. Mobile nav accessibility: added aria-controls and aria-expanded state updates
6. Social links consistency: unified all templates to use site.social_links
7. Homepage excerpts: evaluated the suggestion, kept full content with CSS clamp (with rationale)

How the Session Worked

Each prompt built on the previous result:

1. “Create a new theme like this” – got the base theme
2. “Article briefs should be at least 10 lines” – adjusted excerpt length
3. “Keep format/line separators in briefs” – switched to rendering full HTML with CSS height-clamp
4. “Extract about page info to the homepage” – added hero section with author bio
5. “Make mermaid support built-in” – refactored mermaid integration and all posts
6. “Clean up all minima information” – found and removed every trace
7. “Write a local plugin to replace jekyll-remote-include” – created the plugin
8. “Apply suggestions from Copilot” – processed 7 review comments

Claude Code ran bundle exec jekyll build after every change and verified the output. When it switched SCSS from @import to @use, it confirmed deprecation warnings disappeared. When it created the local plugin, it verified the about page still rendered correctly.

The Result

The blog now runs on a fully local theme:

• Dark/light mode with system preference detection and localStorage persistence
• Sticky header with responsive mobile navigation and ARIA attributes
• Built-in mermaid via standard fenced code blocks
• Giscus comments synced with site theme
• Production-only Google Analytics
• Syntax highlighting for both light and dark themes
• Zero external theme or plugin gem dependencies

All source lives in the repository. Deployable on GitHub Pages directly.

Later Iterations

Material 3 Expressive Redesign

In a follow-up session, the entire UI was re-themed with Material 3 Expressive design language – again using Claude Code:

• Seed color: #6750A4 (M3 purple), generating a full tonal palette for light and dark schemes
• Typography: switched from Inter to Outfit, mapped to the M3 type scale (Display / Headline / Title / Body / Label)
• Shape system: pill-shaped tags and nav indicators (border-radius: 9999px), 12px rounded post cards, 16px rounded images
• Motion: M3 standard and spring easings, hover elevation on post cards (translateY(-2px)), spring scale on social icons
• Components: floating sticky header with backdrop blur, tonal pill chips for tags, circular icon buttons, surface-container card backgrounds

All changes were pure SCSS – no HTML markup changes required. The M3 token system (60+ CSS custom properties) makes future color scheme changes a single-variable edit.

Mermaid Interactive Zoom

Mermaid diagrams gained a click-to-zoom overlay:

• Click any diagram to open a fullscreen modal
• Scroll wheel to zoom (0.1x – 10x), drag to pan
• Touch support: pinch-to-zoom, single-finger pan
• Double-click to reset, Esc or close button to exit
• requestAnimationFrame-based rendering for smooth transforms

Modular M3 Expressive Mermaid Theme

A standalone, reusable Mermaid theme was created at assets/js/mermaid-m3-expressive-theme.js:

• UMD module – works with ES modules (import), CommonJS (require), or as a global (mermaidM3Expressive)
• Provides light, dark, and getTheme(isDark) exports
• Covers all diagram types: flowcharts, sequence, state, class, git graphs, pie charts
• Colors derived from the same M3 tonal palette used by the site
• Reusable in any project – just include the script and pass the theme to mermaid.initialize()

// Example usage in another project
mermaid.initialize({
  theme: 'base',
  themeVariables: mermaidM3Expressive.getTheme(isDark)
});

Thoughts

Claude Code’s performance was impressive, and the generated theme suits my needs. I no longer need to wait for someone with frontend experience to build it for me.

1. Introduction

Robolectric is the de-facto standard for running Android unit tests on the JVM without a device or emulator. Historically, Robolectric used hand-written Java “shadow” classes to approximate the behavior of Android framework native code. In Android O (API 26), Robolectric introduced Native Runtime — a mechanism to load real AOSP native libraries (compiled for host platforms) and delegate Android framework native method calls to them, yielding pixel-accurate graphics, real SQLite behavior, and authentic text layout.

This report documents how the Robolectric Native Runtime works within the AOSP main source tree: its architecture, the native libraries involved, how they are compiled for host platforms, how they are integrated via JNI, and how the shadow layer delegates to them.

2. High-Level Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                        Robolectric Test (JVM)                        │
├──────────────────────────────────────────────────────────────────────┤
│  Test Code (JUnit)                                                   │
│       │                                                              │
│       ▼                                                              │
│  Android Framework Classes (android.graphics.*, android.database.*)  │
│       │  (bytecode-instrumented by Robolectric Sandbox)              │
│       ▼                                                              │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │           Shadow Layer (ShadowNative* classes)                 │  │
│  │  ShadowNativePaint, ShadowNativeBitmap, ShadowNativeCanvas,   │  │
│  │  ShadowNativeSQLiteConnection, ShadowNativeTypeface, ...      │  │
│  │       │                                                        │  │
│  │       ▼                                                        │  │
│  │  Natives Delegate Classes (*Natives.java)                      │  │
│  │  PaintNatives, BitmapNatives, SQLiteConnectionNatives, ...     │  │
│  │       │  (declare Java native methods)                         │  │
│  │       ▼                                                        │  │
│  │  DefaultNativeRuntimeLoader                                    │  │
│  │  - Detects OS/arch, extracts .so/.dylib/.dll from JAR          │  │
│  │  - Sets system properties for class registration               │  │
│  │  - Calls System.load() on the native library                   │  │
│  │  - Copies fonts, ICU data to temp directory                    │  │
│  └────────────────────────────────────────────────────────────────┘  │
│       │  JNI / System.load()                                         │
│       ▼                                                              │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │      Host Native Shared Library (libandroid_runtime.so)        │  │
│  │      ┌──────────────────────────────────────────────────────┐  │  │
│  │      │ HostRuntime.cpp (JNI_OnLoad entry point)             │  │  │
│  │      │  → register_android_core_classes()                   │  │  │
│  │      │  → register_android_graphics_classes()               │  │  │
│  │      │  → loadIcuData(), property_initialize_ro_cpu_abilist │  │  │
│  │      └──────────────────────────────────────────────────────┘  │  │
│  │      ┌──────────────────────────────────────────────────────┐  │  │
│  │      │ libhwui (statically linked for host)                 │  │  │
│  │      │  - Skia CPU pipeline (HWUI_NULL_GPU mode)            │  │  │
│  │      │  - Bitmap, Canvas, Paint, Path, Typeface, etc.       │  │  │
│  │      │  - Text: LineBreaker, MeasuredText, TextRunShaper    │  │  │
│  │      │  - RenderNode, RenderEffect, HardwareRenderer        │  │  │
│  │      └──────────────────────────────────────────────────────┘  │  │
│  │      ┌──────────────────────────────────────────────────────┐  │  │
│  │      │ Other statically linked host libraries               │  │  │
│  │      │  libskia, libandroidfw, libsqlite, libminikin,       │  │  │
│  │      │  libharfbuzz_ng, libft2, libpng, libjpeg, libwebp,   │  │  │
│  │      │  libicu, libz, libhostgraphics, ...                  │  │  │
│  │      └──────────────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘

3. Supported Host Platforms

The native runtime supports the following host configurations (from DefaultNativeRuntimeLoader.isSupported()):

Source evidence: DefaultNativeRuntimeLoader.java lines 325–329:

return (OsUtil.isMac()
        && (Objects.equals(arch(), "aarch64") || Objects.equals(arch(), "x86_64")))
    || (OsUtil.isLinux() && Objects.equals(arch(), "x86_64"))
    || (OsUtil.isWindows() && Objects.equals(arch(), "x86_64"));

4. Native Libraries: What Gets Compiled & How

4.1 The Core Library: libandroid_runtime

The primary native shared library is libandroid_runtime, defined in frameworks/base/core/jni/Android.bp (line 512).

Key characteristics:

• host_supported: true — enabled for host builds
• Inherits from libandroid_runtime_defaults which includes both core JNI and graphics JNI code
• On host, uses a static linking strategy for most dependencies (libhwui, libskia, libsqlite, etc.) to produce a self-contained .so

Host-specific source files (frameworks/base/core/jni/Android.bp lines 440–508):

platform/host/HostRuntime.cpp      ← Main JNI_OnLoad entry point
platform/host/native_window_jni.cpp ← Stub native window for host

Host-specific static libraries (line 451–479):

libandroidfw          (Android Framework resources)
libhostgraphics       (Host stubs for graphics surfaces)
libhwui               (Hardware UI / graphics engine)
libft2                (FreeType font rendering)
libharfbuzz_ng        (Text shaping)
libminikin            (Text layout)
libsqlite             (SQLite database engine)
libskia               (2D graphics engine)
libpng, libjpeg, libwebp  (Image codecs)
libz                  (Compression)
libnativehelper_jvm   (JNI helper for host JVM)
libultrahdr           (Ultra HDR support)

Source evidence: frameworks/base/core/jni/Android.bp lines 451–479.

4.2 libhwui — The Graphics Engine

libhwui is defined in frameworks/base/libs/hwui/Android.bp (line 726) with host_supported: true.

Host mode differences:

• Compiled with -DHWUI_NULL_GPU — disables GPU acceleration, uses Skia CPU pipeline only
• Uses platform/host/ stub implementations for:
  • renderthread/RenderThread.cpp — simplified single-threaded rendering
  • renderthread/CacheManager.cpp — no GPU cache needed
  • Readback.cpp — stub readback
  • WebViewFunctorManager.cpp — no WebView support on host
• Includes libhostgraphics as substitute for real libgui/libnativewindow

Source evidence: frameworks/base/libs/hwui/Android.bp lines 699–722:

host: {
    srcs: [
        "platform/host/renderthread/CacheManager.cpp",
        "platform/host/renderthread/RenderThread.cpp",
        ...
    ],
    cflags: [
        "-DHWUI_NULL_GPU",
        "-DNULL_GPU_MAX_TEXTURE_SIZE=4096",
    ],
},

4.3 libhostgraphics — Host Surface Stubs

Defined in frameworks/base/libs/hostgraphics/Android.bp, this library provides host-compatible stubs for Android-specific display and surface APIs:

• ANativeWindow.cpp — stub native window
• Fence.cpp — stub sync fence
• HostBufferQueue.cpp — stub buffer queue
• PublicFormat.cpp — image format utilities
• ADisplay.cpp — stub display

4.4 Pre-V: librobolectric-nativeruntime (Prebuilt)

For Android SDK versions prior to V (VanillaIceCream), the native library is called librobolectric-nativeruntime and ships as prebuilt binaries in two forms:

1. In AOSP: prebuilts/misc/common/robolectric-native-prebuilt/
   • native/linux/x86_64/librobolectric-nativeruntime.so
   • native/mac/librobolectric-nativeruntime.dylib
2. In Gradle/Maven: The nativeruntime-dist-compat artifact (version 1.0.17) published to Maven Central.

Source evidence: prebuilts/misc/common/robolectric-native-prebuilt/Android.bp:

// Releases including and since VanillaIceCream ships with a libandroid_runtime.so
// equivalent to the librobolectric-nativeruntime.so included in this artifact.
name: "robolectric_nativeruntime_native_prebuilt"

4.5 V+ (Android 15+): libandroid_runtime (Built from AOSP)

Starting with Android V, Robolectric uses the same libandroid_runtime.so that AOSP builds for host. This library is packaged as a JAR via a java_genrule:

Source evidence: external/robolectric/Android.bp lines 65–75:

java_genrule {
    name: "libandroid_runtime_jar",
    host_first_srcs: [":libandroid_runtime"],
    out: ["libandroid_runtime.jar"],
    cmd: "mkdir -p ./native/linux/x86_64/ && " +
        "cp $(location :libandroid_runtime) ./native/linux/x86_64/ && " +
        "$(location soong_zip) -o $(location libandroid_runtime.jar) -D ./native",
}

The resulting JAR is then bundled into robolectric-host-android_all (line 123–157).

5. JNI Registration Mechanism

5.1 Two-Phase Registration (V+)

For Android V and above, JNI registration uses a class-name-driven dynamic lookup mechanism. The classes to register are communicated via Java system properties:

System.setProperty("core_native_classes", "android.database.CursorWindow,...");
System.setProperty("graphics_native_classes", "android.graphics.Bitmap,...");
System.setProperty("method_binding_format", "$$robo$$${method}$nativeBinding");

Phase 1 — Core Classes (from HostRuntime.cpp → register_android_core_classes()):

• Reads core_native_classes system property
• Looks up each class name in gRegJNIMap (an unordered_map<string, RegJNIRec>)
• Calls the corresponding register_*() function

Phase 2 — Graphics Classes (from LayoutlibLoader.cpp → register_android_graphics_classes()):

• Reads graphics_native_classes system property
• Uses a similar map in LayoutlibLoader.cpp

5.2 Method Name Rewriting

A critical mechanism is JNI method name rewriting. Normally, JNI maps native void nFoo() in class android.graphics.Paint to a C function Java_android_graphics_Paint_nFoo. But Robolectric’s bytecode instrumentor replaces native methods with Java stubs and creates a separate native binding method with a mangled name.

The format is: $$robo$$<method>$nativeBinding

This is set via:

System.setProperty("method_binding_format", "$$robo$$${method}$nativeBinding");

On the native side, graphics_jni_helpers.h contains jniRegisterMaybeRenamedNativeMethods() which transforms each JNI method registration to use the rewritten name format:

// For method "nInit", registers as "$$robo$$nInit$nativeBinding" instead
std::string modifiedName = jniMethodFormat;
modifiedName.replace(methodNamePos, 9, gMethods[i].name);

Source evidence: frameworks/base/libs/hwui/jni/graphics_jni_helpers.h lines 95–123.

5.3 Bytecode Instrumentation

Robolectric’s ClassInstrumentor (in the sandbox module) transforms native methods:

1. Original: native long nInit() in android.graphics.Paint
2. After instrumentation:
   • nInit() — becomes a non-native Java method that delegates to shadow/handler
   • $$robo$$nInit$nativeBinding() — a new native method for actual JNI binding

When callNativeMethodsByDefault = true on a shadow and no explicit shadow method is found, ShadowWrangler routes the call to the $nativeBinding method:

// ShadowWrangler.java line 166-168
Method method = definingClass.getDeclaredMethod(
    ShadowConstants.ROBO_PREFIX + name + "$nativeBinding", paramTypes);

Source evidence: sandbox/src/main/java/.../ClassInstrumentor.java lines 574–589, ShadowWrangler.java lines 160–174.

6. Core Native Class Registrations

6.1 Core Classes (CORE_CLASS_NATIVES)

These are non-graphics native classes registered for Android V+:

Source evidence: DefaultNativeRuntimeLoader.java lines 59–70.

6.2 Graphics Classes (GRAPHICS_CLASS_NATIVES)

These are graphics-related native classes (40+ classes):

Source evidence: DefaultNativeRuntimeLoader.java lines 73–121.

7. Shadow → Native Delegation Flow

┌──────────────────────────────────────────────────────────────────┐
│  Test code:  Paint paint = new Paint();                          │
│                                                                  │
│  1. Android Paint constructor calls native method nInit()        │
│                                                                  │
│  2. Instrumented nInit() → ClassHandler → ShadowWrangler         │
│                                                                  │
│  3. ShadowWrangler finds ShadowNativePaint                       │
│     → @Implementation nInit() method exists:                     │
│       a) Calls DefaultNativeRuntimeLoader.injectAndLoad()        │
│       b) Ensures native library is loaded                        │
│       c) Delegates to PaintNatives.nInit()                       │
│                                                                  │
│  4. PaintNatives.nInit() is a Java native method                 │
│     → JNI resolves to $$robo$$nInit$nativeBinding                │
│     → Calls C++ Paint_init() in libhwui's jni/Paint.cpp         │
│     → Creates real SkPaint object via Skia                       │
│     → Returns native pointer as jlong                            │
│                                                                  │
│  For V+ with callNativeMethodsByDefault = true:                  │
│  If no explicit shadow method exists, ShadowWrangler             │
│  routes directly to $$robo$$<method>$nativeBinding               │
└──────────────────────────────────────────────────────────────────┘

7.1 Shadow Example: ShadowNativePaint

@Implements(value = Paint.class, minSdk = O, callNativeMethodsByDefault = true)
public class ShadowNativePaint {
    @Implementation(minSdk = O, maxSdk = U.SDK_INT)
    protected static long nInit() {
        DefaultNativeRuntimeLoader.injectAndLoad();  // Ensure library loaded
        ShadowNativeTypeface.ensureInitialized();    // Dependency init
        return PaintNatives.nInit();                 // Delegate to real native
    }
    // For V+, most methods use callNativeMethodsByDefault
    // and don't need explicit shadow implementations
}

Source evidence: shadows/framework/.../ShadowNativePaint.java lines 36–50.

7.2 Shadow Example: ShadowNativeSQLiteConnection

@Implements(className = "android.database.sqlite.SQLiteConnection",
            callNativeMethodsByDefault = true)
public class ShadowNativeSQLiteConnection extends ShadowSQLiteConnection {
    @Implementation(minSdk = O_MR1, maxSdk = U.SDK_INT)
    protected static long nativeOpen(String path, int openFlags, ...) {
        DefaultNativeRuntimeLoader.injectAndLoad();
        return PerfStatsCollector.getInstance()
            .measure("androidsqlite",
                () -> SQLiteConnectionNatives.nativeOpen(path, openFlags, ...));
    }
}

Source evidence: shadows/framework/.../ShadowNativeSQLiteConnection.java lines 46–66.

8. Resource Loading & Initialization

8.1 Native Library Loading Flow

DefaultNativeRuntimeLoader.ensureLoaded()
│
├── 1. Check isSupported() — verify OS/arch
├── 2. Create TempDirectory("nativeruntime")
├── 3. maybeCopyFonts() — extract fonts from JAR to temp dir
│      └── Sets: robolectric.nativeruntime.fontdir=/tmp/.../fonts/
├── 4. maybeCopyIcuData() — extract ICU data file
│      └── Sets: icu.data.path=/tmp/.../icu/icudt68l.dat
│      └── Sets: icu.locale.default=<default locale tag>
├── 5. [V+ only] Set system properties:
│      ├── core_native_classes=android.database.CursorWindow,...
│      ├── graphics_native_classes=android.graphics.Bitmap,...
│      └── method_binding_format=$$robo$$${method}$nativeBinding
├── 6. loadLibrary() — extract .so/.dylib/.dll and System.load()
│      └── Looks up: native/<os>/<arch>/libandroid_runtime.so
├── 7. [V+ only] invokeDeferredStaticInitializers()
│      └── Calls __staticInitializer__ on classes that need
│          deferred init after JNI registration
└── 8. [V+ only] Typeface.loadPreinstalledSystemFontMap()

Source evidence: DefaultNativeRuntimeLoader.java lines 176–218.

8.2 Library Path Convention

Native libraries are stored in JAR resources at:

native/<os>/<arch>/<library_name>

Examples:

native/linux/x86_64/libandroid_runtime.so
native/mac/x86_64/libandroid_runtime.dylib
native/mac/aarch64/libandroid_runtime.dylib
native/windows/x86_64/libandroid_runtime.dll

Source evidence: DefaultNativeRuntimeLoader.java lines 332–334.

8.3 Bundled Resources

The nativeruntime module includes these runtime resources:

9. AOSP Build Integration (Soong)

9.1 Module Dependency Graph

Robolectric_all (java_library_host)
├── Robolectric_nativeruntime (java_library_host)
│   ├── robolectric_nativeruntime_native_prebuilt (pre-V prebuilt .so/.dylib)
│   ├── Robolectric_sandbox
│   ├── Robolectric_resources
│   └── Robolectric_pluginapi
├── Robolectric_shadows_framework (shadows layer)
├── Robolectric_robolectric
├── robolectric-host-android_all (java_library)
│   ├── robolectric_android-all-device-deps (framework JARs)
│   │   ├── framework-all, core-libart-for-host, services, ...
│   ├── libandroid_runtime_jar (native .so in JAR for V+)
│   │   └── :libandroid_runtime (cc_library_shared, host)
│   ├── robolectric_framework_res
│   ├── robolectric_props_jar (build.prop via robolectric.go)
│   └── icu-data_host_robolectric
└── ...

9.2 android_robolectric_test Module Type

Platform tests use the android_robolectric_test Soong module type which:

1. Adds Robolectric_all as a runtime dependency
2. Sets up the classpath with robolectric-host-android_all
3. Runs tests on the host JVM with the native library available

9.3 robolectric_build_props

A custom Soong module (soong/robolectric.go) generates a build.prop file with platform-specific properties (SDK version, codename, etc.) that Robolectric reads at runtime:

// soong/robolectric.go
"ro.build.version.sdk=" + ctx.Config().PlatformSdkVersion().String(),
"ro.build.version.release=" + ctx.Config().PlatformVersionName(),
"ro.build.version.codename=" + ctx.Config().PlatformSdkCodename(),

Source evidence: soong/robolectric.go lines 42–86.

10. JNI_OnLoad & Native Entry Point

When System.load() loads the native library, JNI_OnLoad in HostRuntime.cpp runs:

JNIEXPORT jint JNI_OnLoad(JavaVM* vm, void*) {
    JNIEnv* env = nullptr;
    vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6);

    // Check if base host runtime should be initialized
    string useBaseHostRuntime = getJavaProperty(env, "use_base_native_hostruntime", "true");
    if (useBaseHostRuntime == "true") {
        Vector<String8> args;
        HostRuntime runtime;
        runtime.onVmCreated(env);   // Store JavaVM reference
        runtime.start("HostRuntime", args, false);  // Register JNI + init
    }
    return JNI_VERSION_1_6;
}

HostRuntime::start() triggers:

1. setJniMethodFormat() — reads method_binding_format property for method renaming
2. startReg() → register_android_core_classes() + register_android_graphics_classes()
3. onStarted() → loadIcuData(), property_initialize_ro_cpu_abilist(), set locale

Source evidence: frameworks/base/core/jni/platform/host/HostRuntime.cpp lines 296–306.

11. Version Evolution (Pre-V vs V+)

Source evidence: DefaultNativeRuntimeLoader.java lines 336–343, 387–389.

12. Shadow Inventory

There are 88 ShadowNative* files in shadows/framework/src/main/java/.../shadows/, covering these major subsystems:

13. Compiled Native Library Dependency Tree

Major native libraries statically linked into the host libandroid_runtime.so:

libandroid_runtime.so (host shared library)
│
├── HostRuntime.cpp — JNI_OnLoad, AndroidRuntime host impl
├── android_database_SQLiteConnection.cpp — SQLite JNI bindings
├── android_database_CursorWindow.cpp — CursorWindow JNI
├── android_view_Surface.cpp — Surface JNI
├── android_animation_PropertyValuesHolder.cpp — Animation JNI
├── com_android_internal_util_VirtualRefBasePtr.cpp — RefBase JNI
│
├── libhwui (static, compiled with HWUI_NULL_GPU)
│   ├── LayoutlibLoader.cpp / jni_runtime.cpp — Graphics JNI registration
│   ├── jni/Paint.cpp, jni/Bitmap.cpp, jni/Canvas.cpp, ... — All graphics JNI
│   ├── hwui/Bitmap.cpp, hwui/Canvas.cpp, hwui/Typeface.cpp — Core graphics impl
│   ├── pipeline/skia/SkiaCpuPipeline.cpp — CPU-only rendering
│   └── platform/host/* — Host-specific stubs
│
├── libskia (static) — Google's 2D graphics engine
├── libminikin (static) — Android text layout engine
├── libharfbuzz_ng (static) — Unicode text shaping
├── libft2 (static) — FreeType font rasterization
├── libandroidfw (static) — Android framework (resources, assets)
├── libsqlite (static) — SQLite database engine
├── libpng (static) — PNG codec
├── libjpeg (static) — JPEG codec
├── libwebp-decode/encode (static) — WebP codec
├── libz (static) — zlib compression
├── libhostgraphics (static) — Host stubs for ANativeWindow, Fence, etc.
├── libicu{i18n,uc} (static) — ICU internationalization
├── libbase (static) — Android base/logging
├── libcutils (static) — Android core utilities
├── liblog (static) — Android logging
└── libutils (static) — Android utility library

14. The nativeruntime-dist-compat Maven Artifact

For external (non-AOSP) Gradle builds, Robolectric distributes prebuilt native libraries as the Maven artifact org.robolectric:nativeruntime-dist-compat (current version: 1.0.17).

This JAR contains pre-compiled native shared libraries for all supported platforms:

native/linux/x86_64/librobolectric-nativeruntime.so
native/mac/x86_64/librobolectric-nativeruntime.dylib
native/mac/aarch64/librobolectric-nativeruntime.dylib
native/windows/x86_64/robolectric-nativeruntime.dll

It is used in the Gradle build via:

// nativeruntime/build.gradle.kts
implementation(libs.robolectric.nativeruntime.dist.compat)

The CI workflow .github/workflows/graphics_tests.yml runs graphics tests on all four platform configurations (Linux x86_64, macOS x86_64, macOS arm64, Windows x86_64).

Source evidence: gradle/libs.versions.toml line 2, 186.

15. Some AOSP Changes for Native Runtime

15.1 Thematic Analysis

Phase 1: Foundation (Jan–Apr 2022)

The first wave of changes created the entire build infrastructure from scratch:

• Build target creation — I19296fc4d established the initial robolectric_native_runtime build target in frameworks/base/core/jni/Android.bp, a cc_library_shared with host_supported: true. This single CL (+164 lines) laid the foundation for the entire effort.

• Distribution pipeline — Ieb351f5b added the library to $DIST_DIR/robolectric/nativeruntime, and I5a99f9f7 similarly distributed the ICU dat file required for text processing.

• Core JNI classes — A rapid series of CLs incrementally added JNI registration for the most critical Android framework classes:
  • I9661646a: Matrix and initial graphics JNI
  • I046e1447: Bitmap and BitmapFactory — enabling image decoding
  • I6071aa4d: FontFamily with namespace handling (com.android.internal.graphics.fonts vs android.graphics.fonts for different SDK levels)
  • I369181f0: Typeface and text classes — completing text layout support
• Compatibility guard — I7aab27c7 added an SDK-level check to only register graphics JNI for SDK >= 26 (Android O), avoiding crashes from missing Matrix JNI fields in older versions.

Phase 2: libnativehelper and ICU (May–Sep 2022)

• libnativehelper adaptation (Icaef0cb0) — Changed the Buffer internals accessor class from a LayoutLib class to org.robolectric.nativeruntime.NIOAccess, and enabled a static cc_library for the host build. This was essential because libnativehelper provides core JNI helper functions used throughout the native runtime.

• ICU locale property (Ia219a6c2) — Updated the system property name used for ICU’s default language tag, ensuring proper locale handling in host text operations.

Phase 3: macOS Support (Jan 2023)

• Ic51c46c8 (“Add support for building RNG on Mac”, +75/-57) was a significant change that:
  • Updated the robolectric_native_runtime target with macOS-specific build rules
  • Excluded AnimatedImageDrawable from Mac builds (requires Linux’s epoll)
  • Included CursorWindow.cpp for Mac (SQLite cursor support)
  • Validated with ShadowNativeMatrixTest on Mac artifacts

Phase 4: Windows Platform (Dec 2023 – Mar 2024)

The Windows porting effort required changes across multiple AOSP repositories:

• Ie932ddec (“Enable host Windows build”) — Initial Windows build target. SQLite JNI was initially disabled because CursorWindow.cpp and SQLite JNI needed mmap/ashmem.

• Ie72a5f04 (“ashmem-host for Windows”, system/core) — Migrated to tmpfile/fileno for temp file operations (supported on MinGW), enabling CursorWindow on Windows.

• I138064847 (“SQLite JNI in Windows”) — Used libbase’s MappedFile for cross-platform mmap operations in CursorWindow.cpp and android_database_SQLiteConnection.cpp.

• I38b67e6f (“AnimatedImageDrawable for Mac and Windows”) — Re-enabled AnimatedImageDrawable on Mac/Windows by disabling the AnimatedEndListener mechanism (which requires native Looper, unavailable on host).

Two changes landed on AOSP main to improve portability for all host builds:

• I77b6b548 — Replaced raw mmap/munmap calls with MappedFile in CursorWindow
• I535449c2 — Same replacement in android_database_SQLiteConnection

Phase 5: ICU and Locale Improvements (Jan–Mar 2024)

• I7c0ffffe — Changed the ICU language tag property from robolectric.nativeruntime.languageTag to icu.locale.default for alignment with upstream LayoutLib.
• I894b9b79 (+84/-18) — Backported the latest LayoutLib ICU loading logic to the hostruntime-dev branch, improving internationalization support.
• I21e71152 — Used the minimal "C" numeric locale in strtof calls to prevent float parsing failures in locales where commas are decimal separators (e.g., German locale).

Phase 6: Hardware Rendering and Surface Support (May–Jul 2024)

This phase added hardware-accelerated rendering support (via CPU-only Skia pipeline):

• Ic037fea1 — Fixed Mac pixel color swap issue by using kN32_SkColorType (architecture- dependent) instead of a hardcoded color type for SkiaHostPipeline.
• I949382eb — Extended ImageReader and HardwareRenderer.syncAndDrawFrame support to Android Q and R (previously only Android S+).
• If52fe2a4 (+46/-44) — Synchronized hwui files with sc-layoutlib-native branch, enabling CanvasContext, RootRenderNode, RenderThread, animation logic, and more.
• I74a7d09e — Fixed hwui compile errors so m libhwui works with the Android toolchain (not just the host toolchain).
• Ieca45f62 — Un-ifdef’d Surface.lockCanvas and Surface.unlockCanvasAndPost (they compile fine on host).
• I22038e78 — Added android_view_ThreadedRenderer_setSurfacePtr for backwards compatibility with Android O/P.
• I1631d08d — Fixed frameinfo data conversion from the 9-length (Android R) to 12-length (Android S+) format for proper HW rendering support.
• Ic80c6aef — Added FileDescriptor-based ImageDecoder.nDecode variant.

Phase 7: Path APIs and Newer SDK Support (Aug 2024 – Jan 2026)

• Iab0c43c7 (+84) — Backported PathIterator JNI from Android U.
• Ib980365a (+74/-40) — Added nConicTo, nRConicTo, nInterpolate, nGetGenerationID, and nIsInterpolatable from Android U’s Path API.
• I217e91ae — Added a host-specific variant of PathIterator.nNext JNI.
• I96475c4b (+12) — Added unexported symbol list for Mac to prevent symbol clashes between librobolectric-nativeruntime (pre-V) and libandroid_runtime (V+) for ANativeWindow and Minikin symbols.
• I19e69cd5 (+45/-2, Jul 2025) — Added android.text.Hyphenator JNI support with a configurable hyphen data directory via system property.
• I8a533353 (+3/-1, Jan 2026) — Bound BitmapRegionDecoder JNI for region-based image decoding.

15.2 Development Branch Strategy

android12-hostruntime-dev (main development branch)
    │
    │   Most RNR-specific changes land here first
    │   Based on Android 12 codebase
    │   Contains customizations that can't go to main
    │     (host-only ifdef's, backported APIs, etc.)
    │
    ├── Changes stay here: JNI additions, host-only adaptations
    │
    └── Portable improvements → cherry-picked to main
            │
            ▼
        main (AOSP trunk)
            Only gets changes that benefit ALL host builds
            (LayoutLib + Robolectric)
            e.g., MappedFile portability improvements

The android12-hostruntime-dev branch serves as a long-running development branch where RNR-specific modifications are made independently of AOSP main. This approach is necessary because:

1. Many changes are host-only — They add #ifdef __ANDROID__ guards, host-specific code paths, or backported APIs that don’t belong in the shipping Android platform.

2. The base is Android 12 — The native runtime needs to support older SDK levels (O through R) with a stable codebase, while main continuously evolves.

3. Select improvements get upstreamed — Portable changes (like MappedFile for mmap) that benefit both Robolectric and LayoutLib are cherry-picked to AOSP main.

15.3 Cross-Repository Impact

The changes touch 6 AOSP repositories, demonstrating the breadth of modifications needed:

15.4 Key Engineering Patterns

1. Incremental JNI binding — Rather than a single massive CL, classes were added in small groups (Matrix → Bitmap → Font → Typeface), each tested independently.

2. Platform-first, then broaden — Linux was first, then Mac (Jan 2023), then Windows (Dec 2023), with each platform bringing unique challenges (epoll, mmap, symbol visibility).

3. Upstream when possible — Portable improvements (MappedFile) go to main; host-only customizations stay on android12-hostruntime-dev.

4. API backporting — Newer APIs (PathIterator from U, Hyphenator) are backported to the hostruntime-dev branch so RNR can support them across all SDK levels.

5. Shared infrastructure with LayoutLib — Many patterns (ICU loading, locale handling, JNI method format) are shared with Android Studio’s LayoutLib, reducing duplication.

16. Summary

Robolectric’s Native Runtime achieves high-fidelity Android emulation on the JVM by:

1. Compiling real AOSP C++ libraries (libhwui, libskia, libsqlite, libminikin, etc.) for host platforms (Linux/macOS/Windows) with GPU support disabled (HWUI_NULL_GPU)

2. Packaging them as a single shared library (libandroid_runtime.so) that statically links all dependencies

3. Using bytecode instrumentation to redirect native method calls through a renaming scheme ($$robo$$<method>$nativeBinding) that allows the shadow layer to intercept calls when needed while defaulting to real native execution

4. Providing 88+ shadow classes that ensure correct initialization, lazy loading of the native library, and version-specific API compatibility across Android O through V+

5. Bundling runtime resources (fonts, ICU data, build properties) that the native code requires for correct operation

This approach delivers pixel-accurate graphics rendering, real SQLite behavior, and authentic text layout in Robolectric tests, well beyond what hand-written shadows alone could provide.

1) Overview

.apkm is a file format created by APKMirror to distribute Android applications that are built using Android App Bundle (AAB). Since Google Play generates device-specific split APK sets from AAB files at install time, third-party distributors like APKMirror cannot distribute a single monolithic APK for bundle-based apps. The .apkm format solves this by packaging the base APK together with all available split APKs into a single distributable archive.

An .apkm file is installed on-device using the APKMirror Installer application or APKMInstaller application from me, or manually via adb install-multiple.

2) File structure

An .apkm file is a standard ZIP archive with the .apkm file extension. The archive is signed by APKMirror using JAR signing (META-INF/) and contains metadata, an app icon, split APKs, and an installer URL shortcut.

2.1) Real-world example — Google Play Store 50.3.27

Directory structure of com.android.vending v50.3.27 from APKMirror (48.0 MB compressed, 106.3 MB uncompressed, 42 entries):

com.android.vending_50.3.27-31_[...].apkm (ZIP archive)
│
│  # Archive-level signing (JAR Signature v1)
├── META-INF/MANIFEST.MF                                  # SHA1 digests of all entries
├── META-INF/APKMIRRO.SF                                  # Signed manifest
├── META-INF/APKMIRRO.RSA                                 # APKMirror certificate (self-signed)
│
│  # Metadata
├── info.json                                              # Package metadata (required)
├── icon.png                                               # App icon, 96x96 PNG (optional)
├── APKM_installer.url                                     # Windows .url shortcut to APKMirror Installer page
│
│  # Base APK
├── base.apk                                               # 53.7 MB uncompressed
│
│  # ABI configuration splits (3 architectures)
├── split_config.arm64_v8a.apk                             # 8.6 MB
├── split_config.armeabi_v7a.apk                           # 5.4 MB
├── split_config.x86.apk                                   # 9.1 MB
│
│  # Language configuration splits (24 languages)
├── split_config.ar.apk
├── split_config.de.apk
├── split_config.en.apk
├── split_config.es.apk
├── split_config.et.apk
├── split_config.fi.apk
├── split_config.fr.apk
├── split_config.hi.apk
├── split_config.hu.apk
├── split_config.in.apk
├── split_config.it.apk
├── split_config.ja.apk
├── split_config.ko.apk
├── split_config.ms.apk
├── split_config.nl.apk
├── split_config.pl.apk
├── split_config.pt.apk
├── split_config.ru.apk
├── split_config.sv.apk
├── split_config.th.apk
├── split_config.tr.apk
├── split_config.uk.apk
├── split_config.vi.apk
├── split_config.zh.apk
│
│  # Dynamic feature module: phonesky_data_loader
├── split_phonesky_data_loader.apk                         # Module base (16 KB)
├── split_phonesky_data_loader.config.arm64_v8a.apk        # Module ABI split
├── split_phonesky_data_loader.config.armeabi_v7a.apk
├── split_phonesky_data_loader.config.x86.apk
│
│  # Dynamic feature module: phonesky_webrtc_native_lib
├── split_phonesky_webrtc_native_lib.apk                   # Module base (16 KB)
├── split_phonesky_webrtc_native_lib.config.arm64_v8a.apk  # Module ABI split (6.6 MB)
├── split_phonesky_webrtc_native_lib.config.armeabi_v7a.apk
└── split_phonesky_webrtc_native_lib.config.x86.apk

2.2) Compression

Most entries use DEFLATED compression. Only small non-APK assets (icon.png, APKM_installer.url) are STORED uncompressed. In this example, DEFLATED achieves ~47% compression on the contained APK files (106 MB → 48 MB).

2.3) Archive-level signing

The .apkm archive itself is signed using JAR Signature (v1) by APKMirror. The META-INF/ directory contains:

This allows installers to verify that the archive contents have not been tampered with after distribution by APKMirror.

2.4) Naming conventions

The naming follows the conventions used by Android’s bundletool when generating APK sets from AAB files.

3) Metadata — info.json

The .apkm archive includes an info.json at its root, describing the package, available configurations, and APKMirror-specific distribution metadata.

3.1) Real-world example — Google Play Store 50.3.27

{
    "apkm_version": 5,
    "apk_title": "Google Play Store 50.3.27-31 [0] [PR] 875414499 (nodpi) (Android 12L+)",
    "app_name": "Google Play Store",
    "release_version": "50.3.27-31 [0] [PR] 875414499",
    "variant": "(universal) (nodpi) (Android 12L+)",
    "release_title": "Google Play Store 50.3.27-31 [0] [PR] 875414499 (nodpi) (Android 12L+)",
    "versioncode": "85032730",
    "pname": "com.android.vending",
    "post_date": "2026-02-27 00:48:12",
    "capabilities": [
        "auto",
        "cardboard"
    ],
    "languages": [
        "ar", "de", "en", "es", "et", "fi", "fr", "hi", "hu", "in",
        "it", "ja", "ko", "ms", "nl", "pl", "pt", "ru", "sv", "th",
        "tr", "uk", "vi", "zh"
    ],
    "arches": [
        "arm64-v8a",
        "armeabi-v7a",
        "x86"
    ],
    "dpis": [
        "nodpi"
    ],
    "min_api": "32",
    "accent_color": "4084f4",
    "apk_id": 12692714,
    "release_id": 12691902
}

3.2) Field definitions

Core fields

Configuration fields

Distribution metadata (APKMirror-specific)

4) Format versions

For version 1 archives (no info.json), the installer must parse AndroidManifest.xml from each contained APK to determine package name, version, and split configuration.

5) Split APK types

The split APKs within an .apkm file correspond to Android’s split APK mechanism introduced in Android 5.0 (API 21). The following split types may be present:

5.1) ABI splits

Contain native libraries (.so files) for a specific CPU architecture.

5.2) Screen density splits

Contain drawable resources for a specific screen density.

5.3) Language splits

Contain string resources and other locale-specific resources for a particular language or locale. In the Google Play Store example, 24 language splits are included:

ar, de, en, es, et, fi, fr, hi, hu, in, it, ja, ko, ms, nl, pl, pt, ru, sv, th, tr, uk, vi, zh

Language split sizes range from ~340 KB (split_config.et.apk) to ~860 KB (split_config.zh.apk).

5.4) Dynamic feature modules

Contain code and resources for on-demand or install-time feature modules defined in the app’s build.gradle. These follow the pattern split_<module_name>.apk and may have their own ABI configuration splits.

In the Google Play Store example, two feature modules are present:

The phonesky_webrtc_native_lib module’s ABI splits are notably large (6.6 MB for arm64-v8a) because they contain the WebRTC native library.

6) Installation

6.1) Using APKMirror Installer

The recommended method. The APKMirror Installer app:

1. Opens the .apkm file and reads info.json (or parses APKs directly for v1).
2. Selects the appropriate splits for the device (matching ABI, density, and language).
3. Installs the base APK and selected splits using the Android PackageInstaller session API (createSession → openSession → openWrite for each APK → commit).

6.2) Using APKMInstaller

APKMInstaller is an open-source, ads-free alternative installer for .apkm files. Built with Kotlin and Jetpack Compose (Material You), it provides:

1. File picker or intent-based opening — browse with the system file picker or tap an .apkm file in any file manager.
2. Package preview — displays app icon, name, package name, version, size, split count, and declared permissions before installing.
3. Step-by-step progress — animated Extract → Verify → Install flow with success/failure states.
4. Split installation — extracts all APKs to a temporary cache directory and installs them together as a single split-APK session using the Android PackageInstaller API.

Requirements: Android 8.0 (API 26)+, “Install unknown apps” permission granted.

6.3) Using adb

For manual installation, extract the archive and use adb install-multiple. You must select only the splits matching your target device:

# Extract the .apkm file (rename to .zip if your tool doesn't recognize .apkm)
unzip com.android.vending_50.3.27-31_*.apkm -d playstore/

# Install on an arm64 device with English language
adb install-multiple \
    playstore/base.apk \
    playstore/split_config.arm64_v8a.apk \
    playstore/split_config.en.apk \
    playstore/split_phonesky_data_loader.apk \
    playstore/split_phonesky_data_loader.config.arm64_v8a.apk \
    playstore/split_phonesky_webrtc_native_lib.apk \
    playstore/split_phonesky_webrtc_native_lib.config.arm64_v8a.apk

Note: When using adb install-multiple, you must only include the ABI splits that match your target device. Including mismatched ABI splits (e.g., x86 on an ARM device) will cause installation to fail. Language splits for non-installed languages are harmless but unnecessary. Feature module base splits and their matching ABI config splits should be included together.

6.4) Programmatic installation (Android)

The following code is derived from APKMInstaller’s implementation. The full process has three stages: extract, verify, and install.

Stage 1 — Extract APKs from the .apkm ZIP

// Open the .apkm file via ContentResolver (works with file pickers, intent shares, etc.)
val apkFiles = mutableListOf<File>()
var totalBytes = 0L
val maxBytes = 2L * 1024 * 1024 * 1024 // 2 GB safety cap

context.contentResolver.openInputStream(apkmUri)?.use { stream ->
    ZipInputStream(stream).use { zip ->
        var entry = zip.nextEntry
        while (entry != null) {
            if (!entry.isDirectory && entry.name.endsWith(".apk")) {
                val outFile = File(cacheDir, entry.name.substringAfterLast('/'))
                outFile.parentFile?.mkdirs()
                FileOutputStream(outFile).use { out ->
                    val written = zip.copyTo(out, bufferSize = 65_536)
                    totalBytes += written
                    require(totalBytes <= maxBytes) { "Package exceeds size limit" }
                }
                apkFiles += outFile
            }
            zip.closeEntry()
            entry = zip.nextEntry
        }
    }
}

// Sort so base.apk is always first
apkFiles.sortWith(compareBy { if (it.name == "base.apk") 0 else 1 })