KotStep Stepper UI Library

KotStep is transitioning from an Android-only library to a Compose Multiplatform (CMP) library. This migration aims to support Android, iOS, Desktop (JVM), and Web (Wasm/JS) while maintaining 100% backward compatibility for the existing V3 DSL API.

Key Migration Principles:

• No Rewrite: The V3 core is already ~97% portable as it uses standard androidx.compose.* imports.
• Gradual Approach: Migration is performed module-by-module to ensure the build remains stable.
• API Preservation: The public API (KotStep(), KotStepScope, step(), and styles) will remain unchanged for Android consumers.
• Scope: The migration focuses on V3. The legacy V2 API (using ConstraintLayout) is explicitly out of scope for multiplatform support and may be deprecated or kept as Android-only.

Planned updates to the API will introduce a slot reservation strategy to control how leadingLabel and trailingLabel affect the stepper layout. Developers will eventually be able to choose between strategies such as:

• Natural: Standard layout behavior.
• AlignToLargest: Ensures all steps align based on the largest measured label in the set.
• Fixed(...): Provides a specific fixed size for the label slots.

The currentStep parameter is a lambda returning a Float. This value drives both the StepState (Todo, Current, Done) and the animation of the connecting lines.

• < 0f: All steps are Todo; lines are empty.
• 0f: Step 0 is Current; Step 1+ are Todo; Line 0 progress is 0%.
• 0.5f: Step 0 is Current; Step 1+ are Todo; Line between Step 0 and 1 is 50% filled.
• 1.0f: Step 0 is Done; Step 1 is Current; Step 2+ are Todo; Line between Step 0 and 1 is 100% filled.
• >= totalSteps: All steps are Done; all lines are 100% completed.

The project defines specific roles to manage the migration and build process:

Critical Rule: Builders are not trusted to verify their own builds. The Navigator is the only role authorized to run Gradle commands and verify that a build is green before merging.

In KotStep V3, currentStep is a Float. This allows for smooth animations of the connecting progress line between steps.

• Whole numbers (e.g., 0f, 1f) represent fully-completed or active steps.
• Fractions (e.g., 0.5f) represent partial progress on the line between two indices.

Value Mapping:

• -1f: All steps are in the Todo state.
• 0f: Index 0 is the Current step.
• 0.5f: 50% progress on the line between index 0 and index 1.
• 1f: Index 1 is Current; index 0 is Done.
• 3f: Index 3 is Current; indices 0-2 are Done.

A task is only considered [x] (DONE) when the following criteria are met:

1. Builder: The checklist row is updated with Owner, Verify command, and Pass/Fail status.
2. Navigator: The Navigator has re-run the gate command. For Kotlin Multiplatform, ensure grep -rn "android\." kotstep/src/commonMain returns no results where applicable.
3. Reviewer: A different track has reviewed the diff. Any violations result in a ticket and the task returning to [~] status.
4. Finalization: Only after these steps are complete is the task marked [x] and committed.

The project uses a delegation model designed for parallel work by multiple agents (e.g., Claude Code, Antigravity, opencode, Codex). The core principle is partitioning by file ownership rather than by phase.

To prevent merge conflicts, agents are assigned disjoint file paths. Two agents only conflict if they attempt to touch the same file. This transforms conflict resolution from a reactive merge process into a proactive prevention and arbitration protocol.

KotStep follows a structured deprecation lifecycle for its V2 APIs. If you are using V2 components, be aware of the following timeline to avoid breaking changes:

• v3.2.0: APIs are marked with a WARNING.
• v3.4.x: APIs remain in maintenance mode.
• v3.5.x: APIs will trigger an ERROR.
• v4.0: APIs are completely removed.

Plan your migration to V3 APIs before version 3.5 to ensure compatibility.

The KotStep V3 API includes leadingLabel and trailingLabel slots. The project is moving towards a more robust implementation that aligns with Jetpack Compose best practices.

Key architectural shifts include:

• Immutability: Step objects are being transitioned from mutable properties (var) to immutable properties (val) to improve Compose state reasoning.
• Slot Handling: DSL defaults are moving from empty composables to null for optional slots, following standard Material patterns (like leadingIcon or suffix).
• Layout Behavior: The current layout reserves cross-axis space to keep step indicators aligned. Future updates aim to implement per-step cached measurements so that reserved space can grow and shrink dynamically based on content, rather than only growing to the largest measured size.

The post-migration architecture separates the shared logic from platform-specific entry points. The :kotstep module becomes a KMP library, while platform-specific applications are created as separate modules.

Module Structure:

• :kotstep (KMP Library):
  • commonMain: Contains the V3 DSL, models, styles, layout components, and progress bars.
  • androidMain: Android-specific implementations.
  • iosMain: iOS-specific implementations.
  • jvmMain: Desktop-specific implementations.
  • wasmJsMain: Web-specific implementations.
  • commonTest: Shared UI tests.
• :app: Existing Android demo app (remains a pure Android module).
• :desktopApp: New Desktop entry point.
• :iosApp: New iOS Xcode project.
• :webApp: New Web (Wasm/JS) entry point.

To ensure the library is truly multiplatform, the commonMain source set must be free of Android-specific dependencies. Perform a 'Grep sweep' to ensure zero occurrences of the following in commonMain:

• android.* packages
• R. (Android Resource class)
• LocalContext
• Toast
• java.* packages

Resource Strategy: The library should ship with zero resources to avoid compose.components.resources dependencies. Move demo assets (like kotlin.xml) to the consumer application's src/main/res/drawable/ folder.