Compose Hot Reload

The hot-reload-runtime-jvm module is the JVM implementation of the hot reload runtime. It is organized into specific source directories to manage how code is treated by the hot reload mechanism itself:

• main (src/main/kotlin): Contains the 'static' parts of the JVM runtime. These use the default o.j.compose.reload package, which is explicitly ignored by the hot reload process to prevent infinite loops or instability.
• kotlinUI (src/main/kotlinUI): Contains UI-related source code. This directory uses the hotReloadUI package, ensuring it is not ignored by hot reload. This allows the hot reload UI itself to be built and updated using the hot reload mechanism.
• dev (src/dev/kotlin): Contains development entry points designed to simplify launching and iterating on specific components during development.

Compose Hot Reload operates in two modes:

• Explicit mode: You manually trigger the reload to apply changes. This is done via the IDE's Reload UI button, a shortcut key, or by running specific Gradle reload tasks.
• Auto mode: Uses Gradle's file-watching and continuous build system to automatically reload when file changes are detected. To enable this, pass the --autoReload or --auto argument in the CLI or configure it in your IDE run settings.

Compose Hot Reload relies on three main components working together during a hot reload session:

1. Agent: A special agent added to the JVM execution when the application is launched in 'hot reload mode'. It participates in orchestration and reloads classes on demand.
2. Runtime: A special 'dev' variant of the runtime added to the classpath. It communicates with the Agent and participates in orchestration by listening for messages and broadcasting UI-related messages (e.g., UIRendered).
3. Recompiler: When the dev runtime is launched, a Gradle Daemon is started in continuous mode. It connects to the orchestration and sends ReloadClassesRequest messages whenever the .class files on the runtime classpath change.

Orchestration is the communication layer between the build tool (e.g., Gradle), the Application, and tools like the IDE.

• Default Mode: The Application under hot reload starts its own orchestration server. Connected clients (like the build tool) can exchange messages via broadcasts. For example, a build tool can broadcast a ReloadClassesRequest after recompilation.
• Client Mode: Tools like the IDE or tests can host their own orchestration server. To make the Application connect to an existing server instead of starting its own, you must instruct it to run in 'client mode' by providing the necessary system properties.

When a client connects to the server, they perform a handshake to establish the connection. The protocol uses a specific magic number 24111602 to identify valid connections.

Handshake Sequence:

1. Client sends Magic Number to Server.
2. Client sends Protocol Version to Server.
3. Server sends Magic Number back to Client.
4. Server sends Protocol Version back to Client.
5. Client sends Introduction to Server.
6. Server sends ClientConnected to Client.

Note: The magic number is 24111602.

Most interaction tools (take_screenshot, get_semantic_tree, click, long_click, type_text, scroll, scroll_to_index, resize_window, and get_ui_error) accept an optional window_id parameter.

Selection Rules:

• window_id provided: Operates on that specific window.
• window_id omitted: Operates on the first registered window (the first Window, singleWindowApplication, or DialogWindow composed and shown during startup).
• window_id not found: Returns Window '<id>' not found.

If you have made changes to the compose-hot-reload source code and want to test them in your own project, follow these steps:

1. Make your code changes.
2. Update the version in gradle.properties (e.g., to 1.0.0-DEBUG).
3. Publish the local build: ./gradlew publishAllPublicationsToLocalRepository.
4. In your target project, configure settings.gradle.kts to use the local repository path:

pluginManagement {
    repositories {
        maven("file://path/to/compose-hot-reload/build/repo")
    }
}

dependencyResolutionManagement {
    repositories {
        maven("file://path/to/compose-hot-reload/build/repo")
    }
}

5. Update the org.jetbrains.compose.hot-reload plugin version in your project to match your debug version:

id("org.jetbrains.compose.hot-reload") version "1.0.0-DEBUG"

6. Run your project as usual.

To use Compose Hot Reload, ensure your project meets these minimum requirements:

• Kotlin: 2.1.20 or higher.
• Compose compiler: 2.1.20 or higher.
• Compose Multiplatform: 1.8.2 or higher (Note: CHR 1.2.0-alpha02 and later requires Compose Multiplatform 1.10.0+).
• Java Target: Must target Java 21 or earlier to be compatible with JetBrains Runtime.
• IDE: IntelliJ IDEA 2025.2.2+ or Android Studio Otter 2025.2.1+ with the Kotlin Multiplatform IDE plugin installed for the best experience.