reis-mobile 0.3.6 → 0.4.0

package/skills/android-media3-cast-integration/references/android/media/media3/cast/create-castplayer.md

@@ -0,0 +1,390 @@
+The [`CastPlayer`](https://developer.android.com/reference/androidx/media3/cast/CastPlayer) is a Jetpack Media3 [Player](https://developer.android.com/reference/kotlin/androidx/media3/common/Player) implementation that supports
+both local playback and casting to a remote Cast-enabled device. [`CastPlayer`](https://developer.android.com/reference/androidx/media3/cast/CastPlayer)
+simplifies adding cast functionality to your app and provides rich features to
+seamlessly switch between local and remote playback. This guide shows you how to
+integrate [`CastPlayer`](https://developer.android.com/reference/androidx/media3/cast/CastPlayer) into your media app.
+
+To integrate Cast with other platforms, see the [Cast SDK](https://developers.google.com/cast/docs/developers).
+
+## Get a Cast-enabled device
+
+To test `CastPlayer`, you need a [Cast-enabled device](https://store.google.com/gb/category/connected_home?hl=en-GB). Choices include Android
+TV, Chromecast, smart speakers, and smart displays. Verify that your device is
+set up and connected to the same Wi-Fi network as your development mobile for
+discovery.
+
+## Add build dependencies
+
+To start using `CastPlayer`, add the AndroidX Media3 and `CastPlayer`
+dependencies to the `build.gradle` file of your app module.
+
+### Kotlin
+
+    implementation("androidx.media3:media3-exoplayer:1.11.0")
+    implementation("androidx.media3:media3-ui:1.11.0")
+    implementation("androidx.media3:media3-session:1.11.0")
+    implementation("androidx.media3:media3-cast:1.11.0")
+
+### Groovy
+
+    implementation "androidx.media3:media3-exoplayer:1.11.0"
+    implementation "androidx.media3:media3-ui:1.11.0"
+    implementation "androidx.media3:media3-session:1.11.0"
+    implementation "androidx.media3:media3-cast:1.11.0"
+
+## Configure your CastPlayer
+
+To configure the [`CastPlayer`](https://developer.android.com/reference/androidx/media3/cast/CastPlayer), update your `AndroidManifest.xml` file with an
+options provider.
+
+### Options provider
+
+The [`CastPlayer`](https://developer.android.com/reference/androidx/media3/cast/CastPlayer) requires an options provider to configure its behavior. For a
+basic setup, you can use the [`DefaultCastOptionsProvider`](https://developer.android.com/reference/androidx/media3/cast/DefaultCastOptionsProvider) by adding it to your
+`AndroidManifest.xml` file. This uses default settings, including the default
+receiver application.
+
+    <application>
+      ...
+      <meta-data
+        android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
+        android:value="androidx.media3.cast.DefaultCastOptionsProvider" />
+      ...
+    </application>
+
+To customize the configuration, implement your own custom `OptionsProvider`. See
+the [CastOptions](https://developer.android.com/media/media3/cast/customize-castoptions) guide to learn how.
+
+### Add a receiver for media transfers
+
+Adding a `MediaTransferReceiver` to your manifest enables the System UI to
+discover Cast-enabled devices on the network and reroute media without opening
+the app activity. For example, a user can change the device playing your app's
+media from the [media notification](https://developer.android.com/media/implement/surfaces/mobile).
+
+    <application>
+      ...
+      <receiver android:name="androidx.mediarouter.media.MediaTransferReceiver" />
+      ...
+    </application>
+
+## Build a CastPlayer
+
+For remote playback with Cast, your app should be able to manage playback even
+when the user isn't interacting with an Activity from your app, such as through
+the system media notification. For this reason, you should create your
+`ExoPlayer` (for local playback) and `CastPlayer` (for remote playback)
+instances in a service, such as [MediaSessionService](https://developer.android.com/media/media3/session/background-playback#service-lifecycle) or [MediaLibraryService](https://developer.android.com/guide/topics/media/session/medialibraryservice).
+First, create your `ExoPlayer` instance and then when building your
+[`CastPlayer`](https://developer.android.com/reference/androidx/media3/cast/CastPlayer) instance, set `ExoPlayer` as the local player instance. You can
+then switch media playback between your mobile and the Cast-enabled device from
+the media notification or the lock screen notification. Media3 uses the **Output
+Switcher** feature to handle player transfers when the output route changes from
+local to remote or from remote to local.
+![Screenshot showing the Output Switcher UI in notifications.](https://developer.android.com/static/media/media3/cast/images/output_switcher.jpeg) Figure 1: (a) Device chip on Media notification (b) Cast-enabled devices shown on tapping the device chip (c) Device chip on Lock screen notification
+
+
+### Kotlin
+
+```kotlin
+override fun onCreate() {
+  super.onCreate()
+
+  val exoPlayer = ExoPlayer.Builder(context).build()
+  val castPlayer = CastPlayer.Builder(context).setLocalPlayer(exoPlayer).build()
+
+  mediaSession = MediaSession.Builder(context, castPlayer).build()
+}
+```
+
+### Java
+
+```java
+@Override
+public void onCreate() {
+  super.onCreate();
+
+  ExoPlayer exoPlayer = new ExoPlayer.Builder(context).build();
+  CastPlayer castPlayer = new CastPlayer.Builder(context).setLocalPlayer(exoPlayer).build();
+
+  mediaSession =
+      new MediaSession.Builder(/* context= */ context, /* player= */ castPlayer).build();
+}
+```
+
+<br />
+
+> [!IMPORTANT]
+> **Important:** The preceding code snippet shows the `onCreate` method of a `MediaSessionService`. In an `Activity`, players should be created in `onStart` or `onResume`.
+
+## Add UI elements
+
+Add a [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton) to your app's UI. Tapping the [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton)
+opens a dialog displaying a list of available Cast-enabled devices on the
+network. When the user selects a device, the media playback is transferred from
+the mobile to the selected receiver device. This section shows you how to add
+the button and listen for events to update your UI when playback switches
+between local and remote devices.
+
+### Set the MediaRouteButton
+
+There are four ways to add the [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton) to your activity's UI. The
+best choice depends on your app's design and requirements.
+
+- **Compose UI**: Add a button composable.
+- **Views UI** :
+  - Add the button to the app bar menu.
+  - Add the button inside `PlayerView`.
+  - Add the button as a standard `View`.
+
+![Screenshot showing the MediaRouteButton in the UI.](https://developer.android.com/static/media/media3/cast/images/cast.jpeg) Figure 2: (a) MediaRouteButton in menu bar, (b) as a View, (c) in PlayerView, and (d) Dialog of Cast-enabled devices.
+
+> [!IMPORTANT]
+> **Important:** To use the [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton) in Views UI, the containing activity must be a subclass of `FragmentActivity`.
+
+> [!TIP]
+> **Tip:** These screenshots are from the [demo-session](https://github.com/androidx/media/tree/release/demos/session) apps in Media3. You can checkout the app to see an example of `CastPlayer` implementation.
+
+#### Add a Composable `MediaRouteButton` to the Player
+
+You can add the [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton) Composable to your player's UI. For more
+information, see the [Compose](https://developer.android.com/media/media3/ui/compose) guide.
+
+
+```kotlin
+@Composable
+fun PlayerComposeView(player: Player, modifier: Modifier = Modifier) {
+  var controlsVisible by remember { mutableStateOf(false) }
+
+  Box(
+    modifier = modifier.clickable { controlsVisible = true },
+    contentAlignment = Alignment.Center,
+  ) {
+    PlayerSurface(player = player, modifier = modifier)
+    AnimatedVisibility(visible = controlsVisible, enter = fadeIn(), exit = fadeOut()) {
+      Box(modifier = Modifier.fillMaxSize()) {
+        MediaRouteButton(modifier = Modifier.align(Alignment.TopEnd))
+        PrimaryControls(player = player, modifier = Modifier.align(Alignment.Center))
+      }
+    }
+  }
+}
+
+@Composable
+fun PrimaryControls(player: Player, modifier: Modifier = Modifier) {
+  // ...
+}
+```
+
+<br />
+
+#### Add the `MediaRouteButton` to the PlayerView
+
+You can add the [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton) directly within the [PlayerView](https://developer.android.com/guide/topics/media/ui/playerview)'s UI
+controls. After setting the [MediaController](https://developer.android.com/guide/topics/media/session/mediacontroller) as the player for your
+`PlayerView`, provide a `MediaRouteButtonViewProvider` to display the Cast
+button on the Player.
+
+
+### Kotlin
+
+```kotlin
+override fun onStart() {
+  super.onStart()
+
+  playerView.player = mediaController
+  playerView.setMediaRouteButtonViewProvider(MediaRouteButtonViewProvider())
+}
+```
+
+### Java
+
+```java
+@Override
+public void onStart() {
+  super.onStart();
+
+  playerView.setPlayer(mediaController);
+  playerView.setMediaRouteButtonViewProvider(new MediaRouteButtonViewProvider());
+}
+```
+
+<br />
+
+#### Add the `MediaRouteButton` to the app bar menu
+
+To set up a [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton) in the app bar menu, create an XML menu and
+override `onCreateOptionsMenu` in your `Activity`.
+
+    <menu xmlns:android="http://schemas.android.com/apk/res/android"
+             xmlns:app="http://schemas.android.com/apk/res-auto">
+      <item android:id="@+id/media_route_menu_item"
+        android:title="@string/media_route_menu_title"
+        app:showAsAction="always"
+        app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider"/>
+    </menu>
+
+
+### Kotlin
+
+```kotlin
+override fun onCreateOptionsMenu(menu: Menu): Boolean {
+  // ...
+  menuInflater.inflate(R.menu.sample_media_route_button_menu, menu)
+  val menuItemFuture: ListenableFuture<MenuItem> =
+    MediaRouteButtonFactory.setUpMediaRouteButton(context, menu, R.id.media_route_menu_item)
+  Futures.addCallback(
+    menuItemFuture,
+    object : FutureCallback<MenuItem> {
+      override fun onSuccess(menuItem: MenuItem?) {
+        // Do something with the menu item.
+      }
+
+      override fun onFailure(t: Throwable) {
+        // Handle the failure.
+      }
+    },
+    executor,
+  )
+  // ...
+  return true
+}
+```
+
+### Java
+
+```java
+@Override
+public boolean onCreateOptionsMenu(Menu menu) {
+  // ...
+  getMenuInflater().inflate(R.menu.sample_media_route_button_menu, menu);
+  ListenableFuture<MenuItem> menuItemFuture =
+      MediaRouteButtonFactory.setUpMediaRouteButton(context, menu, R.id.media_route_menu_item);
+  Futures.addCallback(
+      menuItemFuture,
+      new FutureCallback<MenuItem>() {
+        @Override
+        public void onSuccess(MenuItem menuItem) {
+          // Do something with the menu item.
+        }
+
+        @Override
+        public void onFailure(Throwable t) {
+          // Handle the failure.
+        }
+      },
+      executor);
+  // ...
+  return true;
+}
+```
+
+<br />
+
+#### Add the `MediaRouteButton` as a View
+
+You can set up a [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton) in your activity layout.xml.
+
+      <androidx.mediarouter.app.MediaRouteButton
+          android:id="@+id/media_route_button"
+          android:layout_width="wrap_content"
+          android:layout_height="wrap_content"
+          app:mediaRouteButtonTint="@android:color/white" />
+
+To complete the setup for the [`MediaRouteButton`](https://developer.android.com/reference/androidx/mediarouter/app/MediaRouteButton), use the Media3 Cast
+`MediaRouteButtonFactory` in your `Activity` code.
+
+
+### Kotlin
+
+```kotlin
+override fun onCreate(savedInstanceState: Bundle?) {
+  super.onCreate(savedInstanceState)
+
+  findViewById<MediaRouteButton>(R.id.media_route_button)?.also {
+    val unused = MediaRouteButtonFactory.setUpMediaRouteButton(context, it)
+  }
+}
+```
+
+### Java
+
+```java
+@Override
+public void onCreate(Bundle savedInstanceState) {
+  super.onCreate(savedInstanceState);
+  // ...
+  MediaRouteButton button = findViewById(R.id.media_route_button);
+  ListenableFuture<Void> setUpFuture =
+      MediaRouteButtonFactory.setUpMediaRouteButton(context, button);
+}
+```
+
+<br />
+
+### Activity Listener
+
+Create a `Player.Listener` in your `Activity` to listen for changes to media
+playback location. When the `playbackType` changes between `PLAYBACK_TYPE_LOCAL`
+and `PLAYBACK_TYPE_REMOTE`, you can adjust your UI as needed. To prevent memory
+leaks and to confine listener activity to only when your app is visible,
+register the listener in `onStart` and unregister it in `onStop`:
+
+
+### Kotlin
+
+```kotlin
+private val playerListener: Player.Listener =
+  object : Player.Listener {
+    override fun onDeviceInfoChanged(deviceInfo: DeviceInfo) {
+      if (deviceInfo.playbackType == DeviceInfo.PLAYBACK_TYPE_LOCAL) {
+        // Add UI changes for local playback.
+      } else if (deviceInfo.playbackType == DeviceInfo.PLAYBACK_TYPE_REMOTE) {
+        // Add UI changes for remote playback.
+      }
+    }
+  }
+
+override fun onStart() {
+  super.onStart()
+  mediaController.addListener(playerListener)
+}
+
+override fun onStop() {
+  super.onStop()
+  mediaController.removeListener(playerListener)
+}
+```
+
+### Java
+
+```java
+private final Player.Listener playerListener =
+    new Player.Listener() {
+      @Override
+      public void onDeviceInfoChanged(DeviceInfo deviceInfo) {
+        if (deviceInfo.playbackType == DeviceInfo.PLAYBACK_TYPE_LOCAL) {
+          // Add UI changes for local playback.
+        } else if (deviceInfo.playbackType == DeviceInfo.PLAYBACK_TYPE_REMOTE) {
+          // Add UI changes for remote playback.
+        }
+      }
+    };
+
+@Override
+protected void onStart() {
+  super.onStart();
+  mediaController.addListener(playerListener);
+}
+
+@Override
+protected void onStop() {
+  super.onStop();
+  mediaController.removeListener(playerListener);
+}
+```
+
+<br />
+
+For more information about listening and responding to playback events, see the
+[player events](https://developer.android.com/media/media3/exoplayer/listening-to-player-events) guide.

package/skills/android-media3-cast-integration/references/android/media/media3/cast/customize-castoptions.md

@@ -0,0 +1,93 @@
+To configure your app's Cast session, provide an [`OptionsProvider`](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/OptionsProvider). Use the
+[`CastOptions`](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/CastOptions) object built by the provider to set the receiver application ID,
+manage session lifecycles, and customize media playback behavior.
+
+## Use the default options provider
+
+For a basic setup that uses the default Cast receiver application, add the
+`DefaultCastOptionsProvider` to your app's `AndroidManifest.xml` file:
+
+    <application>
+      ...
+      <meta-data
+        android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
+        android:value="androidx.media3.cast.DefaultCastOptionsProvider" />
+      ...
+    </application>
+
+## Create a custom options provider
+
+For more advanced configurations, such as setting a custom receiver application
+ID, you need to create your own `OptionsProvider`.
+
+### 1. Declare the provider in your manifest
+
+First, declare your custom provider in `AndroidManifest.xml`. Make sure to use
+the fully qualified class name.
+
+    <application>
+      ...
+      <meta-data
+        android:name="com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
+        android:value="path.to.your.class.MyCustomCastOptionsProvider" />
+      ...
+    </application>
+
+### 2. Implement the OptionsProvider interface
+
+Next, create a class that implements the `OptionsProvider` interface. In this
+class, you must override `getCastOptions()` to return a `CastOptions` instance.
+The custom `OptionsProvider` class is where you configure your Cast session, for
+example, by setting your custom receiver application ID.
+
+For more information, see [CastOptions.Builder](https://developers.google.com/android/reference/com/google/android/gms/cast/framework/CastOptions.Builder).
+
+
+### Kotlin
+
+```kotlin
+class MyCustomCastOptionsProvider : OptionsProvider {
+
+  override fun getCastOptions(context: Context): CastOptions {
+    return CastOptions.Builder()
+      .setReceiverApplicationId(APP_ID)
+      .setRemoteToLocalEnabled(true)
+      .build()
+  }
+
+  override fun getAdditionalSessionProviders(context: Context): List<SessionProvider>? {
+    return null
+  }
+
+  companion object {
+    // Add your receiver app ID in <APP_ID>.
+    private const val APP_ID = "<APP_ID>"
+  }
+}
+```
+
+### Java
+
+```java
+public static final class MyCustomCastOptionsProvider implements OptionsProvider {
+
+  // Add your receiver app ID in <APP_ID>.
+  public static final String APP_ID = "<APP_ID>";
+
+  @Override
+  public CastOptions getCastOptions(Context context) {
+    return new CastOptions.Builder()
+        .setReceiverApplicationId(APP_ID)
+        .setRemoteToLocalEnabled(true)
+        .build();
+  }
+
+  @Override
+  @Nullable
+  public List<SessionProvider> getAdditionalSessionProviders(Context context) {
+    return null;
+  }
+}
+```
+
+<br />

package/skills/android-media3-cast-integration/references/android/media/media3/cast/index.md

@@ -0,0 +1,21 @@
+The Media3 [`cast`](https://developer.android.com/reference/androidx/media3/cast/package-summary) module extends your media playback experience to
+Cast devices. It lets your app cast content to [compatible devices](https://developer.android.com/media/media3/cast/create-castplayer#get-device),
+such as TVs and speakers. The [sender](https://developers.google.com/cast/glossary#sender) app acts as a remote controller for media
+playback on the [receiver](https://developers.google.com/cast/glossary#receiver) device. This module integrates with the [Jetpack
+Media3](https://developer.android.com/guide/topics/media/media3) library, so you can use the same `Player` interface and UI
+components for both local and remote playback.
+
+## Media3 CastPlayer
+
+The `CastPlayer` is a media player API included in Media3 that supports both
+local and remote media playback. It implements the `Player` interface to manage
+playback, simplifying the integration of casting into your media experience.
+
+[Go to Media3 CastPlayer](https://developer.android.com/media/media3/cast/create-castplayer)
+
+## Other Cast integrations
+
+The Cast SDK overview explains how to integrate Cast with other platforms, such
+as building a receiver app or integrating with the web sender SDK.
+
+[Explore Cast SDK](https://developers.google.com/cast/docs/developers)

package/skills/android-migrate-xml-views-to-jetpack-compose/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: android-migrate-xml-views-to-jetpack-compose
+description: Provides a structured workflow for migrating an Android XML View to Jetpack
+  Compose. This skill details the step-by-step process, from planning and dependency
+  setup, to theming and layout migration, validation and XML cleanup. Use this skill
+  when you need to migrate an XML View to Jetpack Compose in an Android project. It
+  solves the problem of converting the UI of a legacy XML View into modern, declarative
+  Compose components while maintaining interoperability.
+license: Apache-2.0
+source: https://github.com/android/skills
+routing: manual
+stacks: [android]
+metadata:
+  author: Google LLC
+  last-updated: '2026-08-14'
+  keywords:
+  - Jetpack Compose
+  - migration
+  - XML
+  - Views
+  - interoperability
+  - incremental adoption
+  - UI development
+---
+
+This skill guides through the process of migrating an existing Android XML View
+to Jetpack Compose. It performs a stable, safe and visually consistent
+transition by following a structured, 10-step methodology. This skill migrates
+UI (XML to Jetpack Compose) only.
+
+## Objective
+
+To systematically convert a single legacy XML layout into modern, declarative
+Jetpack Compose UI while maintaining pixel-perfect visual parity and functional
+integrity.
+
+## Summary of the 10-step migration process
+
+1. **Identify the optimal XML candidate for migration**
+2. **Analyze the project and layout**
+3. **Create a plan**
+4. **Capture the XML View UI**
+5. **Set up Compose dependencies and compiler**
+6. **Set up Compose theming**
+7. **Migrate the XML layout to Compose**
+8. **Validate the migration**
+9. **Replace usages**
+10. **XML code removal**
+
+## Detailed steps
+
+### Step 1: Identify the optimal XML candidate for migration
+
+If the user has explicitly specified a target XML layout, proceed to Step 2.
+Otherwise, analyze the codebase to identify the best candidate for migration by
+following the logic in [references/identify-optimal-xml-candidate.md](references/identify-optimal-xml-candidate.md).
+
+### Step 2: Analyze the project and layout
+
+Analyze the identified XML View's structure, hierarchy, and implementation
+details.
+Use [references/analysis-of-the-project-and-layout.md](references/analysis-of-the-project-and-layout.md) to
+guide your technical audit of the layout and surrounding project context.
+
+### Step 3: Create a plan
+
+Using the outputs and analysis done in the Step 1 and 2, generate a
+step-by-step plan for the migration. If you support user interaction, present
+to the user and ask for approval before proceeding. If user interaction is not
+supported, proceed to Step 4 following the generated plan.
+
+### Step 4: Capture the XML View UI
+
+**IF** you support user interaction, ask the user to upload a screenshot of the
+XML View UI or provide an absolute path to a file. Use this image as a visual
+reference for the layout migration in Step 7.
+**ELSE IF** you are able to run an Android emulator, locate an existing
+screenshot test for the XML candidate. If none exists, create one using the
+existing project testing framework. If no framework exists,
+use **UI Automator** or **Espresso** to create a screenshot test with minimum
+required setup. Run the test and take a baseline screenshot of the XML UI.
+**ELSE** proceed to Step 5.
+
+### Step 5: Set up Compose dependencies and compiler
+
+Check `build.gradle` or `libs.versions.toml` for Compose dependencies and
+compiler setup. If missing, use
+[Setup Compose Dependencies and Compiler](references/android/develop/ui/compose/setup-compose-dependencies-and-compiler.md).
+Run a sync to ensure dependencies resolve without errors.
+
+### Step 6: Set up Compose theming
+
+If the project already has Compose theming set up, proceed to Step 7. If Compose
+theming is missing, initialize it. For Material-based projects, follow
+[Material 3 migration guidelines](references/android/develop/ui/compose/designsystems/migrate-xml-theme-to-compose.md).
+For custom design systems, apply expert judgment to migrate XML theming and
+match existing styles.
+**Constraints:** Do not migrate the entire theme. Implement only the minimum
+theming required for the specific XML candidate. Maintain original XML themes
+for interoperability. Maintain existing project code conventions, patterns,
+names and values.
+
+### Step 7: Migrate the XML View to Compose
+
+Convert the XML candidate to Jetpack Compose code, referencing
+[references/xml-layout-migration.md](references/xml-layout-migration.md) and the image from Step 4.
+You must include a **Compose Preview** for the newly created composable to
+facilitate visual verification.
+
+### Step 8: Replace usages
+
+Replace the usages of the migrated XML layout to use the new Compose component.
+
+- To add Compose in Views, use [Compose in Views](references/android/develop/ui/compose/migrate/interoperability-apis/compose-in-views.md).
+- To add Views in Compose, use [Views in Compose](references/android/develop/ui/compose/migrate/interoperability-apis/views-in-compose.md).
+
+### Step 9: Validate the migration
+
+Compare the baseline screenshot image from Step 4 with the rendered Compose
+Preview of the new composable. Ignore string content; focus on layout and
+styling. Iterate on the Compose code until visual parity is achieved. Once
+verified, write a Compose UI test for the new composable.
+
+### Step 10: XML code removal
+
+Delete the migrated XML file and its associated legacy tests. **Caution:** Only
+remove code and resources that are not referenced by other parts of the project.

package/skills/android-migrate-xml-views-to-jetpack-compose/references/analysis-of-the-project-and-layout.md

@@ -0,0 +1,42 @@
+## 1. Project health \& build validation
+
+Before performing any analysis, you must confirm the project is in a functional state.
+\* **Integrity check:** Verify the project syncs (Gradle) and builds successfully.
+\* **Error resolution:** If there are pre-existing build errors or sync failures, you must report these immediately and attempt to fix. **Do not proceed** with migration until a stable baseline is established.
+
+## 2. Compose pattern \& consistency analysis
+
+If Jetpack Compose is already present, you must align with the established implementation style.
+\* **Pattern identification:** Scan the codebase for `@Composable` functions. Identify the project's "Best Practices" regarding state hoisting, composable construction and naming conventions, and file organization.
+\* **Theming review:** Determine how `MaterialTheme` or custom theme systems are implemented.
+\* Identify if the project uses a custom design system theme.
+\* Map how attributes, styles, and other theme components are accessed in Compose.
+
+## 3. Design system \& infrastructure audit
+
+Understand the design system classification (e.g. Material 2, Material 3, or custom design system).
+\* **Resource mapping:** Locate central XML definitions:
+\* `colors.xml` (Light/Dark variants)
+\* `dimens.xml`
+\* `styles.xml` / `themes.xml`
+\* **Hybrid analysis:** Determine if the project is **XML-only** , **Compose-only** , or **Hybrid** .
+\* **Reuse constraint:** If a Compose theming layer (e.g., `AppTheme.kt`) already exists, **DO NOT** generate a new one. You must reuse the existing infrastructure and contribute to it by following its existing implementation pattern.
+
+## 4. Candidate layout decomposition
+
+Analyze the specific XML layout targeted for migration. You must extract and document the following requirements for the new composable:
+\* **Inputs:** UI State objects, primitive parameters, and click listeners.
+\* **Styling:** Specific color constants, typography styles, and shape definitions referenced in the XML.
+\* **Resources:** Identifying string resources, drawables, and dimensions.
+\* **Layout logic:** Modifiers required to replicate the XML constraints (padding, alignment, weight).
+
+## 5. Architectural \& non-UI analysis
+
+Understand the environment in which the UI resides to ensure proper integration.
+\* **State management:** Identify the usage of `ViewModel`, `Flow`, or `LiveData`.
+\* **Dependency Injection:** Check for Hilt, Koin, or manual DI to understand how dependencies are provided to the UI layer.
+\* **Testing \& architecture:** Note the architectural pattern (MVI, MVVM, or custom architecture setup.) and existing UI testing frameworks to ensure the migrated code remains testable. Unless the user explicitly requests, **DO NOT** make any changes to any non-UI code that aren't strictly required for the migration of the XML View.
+
+*** ** * ** ***
+
+> **Pro-tip:** Always prioritize the "Existing infrastructure" over "Default templates." If the project has a custom way of handling spacing or colors, composable code, or any other project layer, your generated Compose code must reflect that specific implementation.