|
| 1 | +# Copilot Instructions for Compose Multiplatform HTML Unified |
| 2 | + |
| 3 | +## Repository Overview |
| 4 | + |
| 5 | +**Compose Multiplatform HTML Unified** is a Kotlin Multiplatform library that provides unified Compose Multiplatform wrappers of common and Material Design APIs for both **rendering-based Compose UI** (Android, desktop JVM, iOS, web Kotlin/Wasm) and **DOM-based Compose HTML**. This library was previously named "Compose Multiplatform Material". |
| 6 | + |
| 7 | +### Repository Statistics |
| 8 | +- **Size**: Medium-large multiplatform project with ~15 modules |
| 9 | +- **Language**: Kotlin (multiplatform) |
| 10 | +- **Build System**: Gradle with Kotlin DSL |
| 11 | +- **Target Platforms**: JVM, Android, iOS, JS (DOM), Wasm-JS (Canvas) |
| 12 | +- **Key Dependencies**: Compose Multiplatform, Kobweb Silk, Material Web Components |
| 13 | + |
| 14 | +## Build Instructions and Environment Setup |
| 15 | + |
| 16 | +### Prerequisites |
| 17 | +- **JDK 17**: Required (as specified in GitHub Actions workflows) |
| 18 | +- **Network Access**: Required for initial builds to download Android Gradle Plugin and other dependencies |
| 19 | +- **Gradle 9.1.0**: Automatically handled by wrapper |
| 20 | + |
| 21 | +**IMPORTANT**: Initial builds require internet access for dependency resolution. Once dependencies are cached, subsequent builds can use `--offline` flag if needed. |
| 22 | + |
| 23 | +**IMPORTANT**: If the project uses snapshot dependencies of other `com.huanshankeji` libraries, especially in a branch other than `main` such as `dev`, refer to the setup instructions at <https://github.com/huanshankeji/.github/blob/main/dev-instructions.md#about-snapshot-dependencies-of-our-library-projects>. |
| 24 | + |
| 25 | +### Build Commands (In Order) |
| 26 | + |
| 27 | +#### 1. Basic Project Setup |
| 28 | +```bash |
| 29 | +./gradlew --version # Verify Gradle 9.1.0 and JDK 17 |
| 30 | +``` |
| 31 | + |
| 32 | +#### 2. Publishing to Local Maven (Primary Development Command) |
| 33 | +```bash |
| 34 | +./gradlew publishToMavenLocal |
| 35 | +``` |
| 36 | +**Important**: Always run `publishToMavenLocal` first when making changes, as mentioned in CONTRIBUTING.md. This ensures libraries compile correctly and validates the build process. |
| 37 | + |
| 38 | +#### 3. Running Tests and Checks (Essential Commands - validated and working) |
| 39 | +```bash |
| 40 | +./gradlew check |
| 41 | +``` |
| 42 | +**Note**: The project has "limited number of tests" according to CONTRIBUTING.md, but this validates what exists. |
| 43 | + |
| 44 | +#### 4. Building Demo Applications |
| 45 | +```bash |
| 46 | +# Build the side-by-side demo (used for GitHub Pages) |
| 47 | +./gradlew :compose-multiplatform-html-unified-demo:sideBySideBrowserDistribution |
| 48 | + |
| 49 | +# Individual platform builds |
| 50 | +./gradlew jsBrowserDistribution # JS DOM version |
| 51 | +./gradlew wasmJsBrowserDistribution # Wasm-JS Canvas version |
| 52 | +``` |
| 53 | + |
| 54 | +### Build Configuration Details |
| 55 | + |
| 56 | +#### Memory Requirements |
| 57 | +- **Gradle JVM**: 2GB memory allocated via `org.gradle.jvmargs=-Xmx2G` in gradle.properties (required for Wasm compilation) |
| 58 | + |
| 59 | +#### Common Build Issues and Workarounds |
| 60 | + |
| 61 | +1. **Network Connectivity**: Initial builds require internet access for Android Gradle Plugin (8.11.2) and other dependencies. If build fails with network errors, ensure internet connectivity. |
| 62 | + |
| 63 | +2. **Memory Issues**: If Wasm compilation fails with OOM, the memory is already optimized in gradle.properties. |
| 64 | + |
| 65 | +3. **Kotlin/JS Store**: The `kotlin-js-store` directory may be generated during JS builds - this should be committed when updated automatically by Gradle commands. |
| 66 | + |
| 67 | +4. **Gradle Daemon**: May timeout on first runs. Use `--no-daemon` flag if needed: `./gradlew check --no-daemon` |
| 68 | + |
| 69 | +### Build Timing and Known Issues |
| 70 | + |
| 71 | +**Timing Expectations**: |
| 72 | +- First build: 5-10 minutes (includes dependency resolution and Wasm compilation) |
| 73 | +- Subsequent builds: 1-3 minutes |
| 74 | +- `publishToMavenLocal`: 3-5 minutes |
| 75 | +- `check` execution: 2-5 minutes (limited tests) |
| 76 | +- Demo builds: 2-4 minutes |
| 77 | + |
| 78 | +**Common Issues**: |
| 79 | +- **Wasm Compilation**: Requires 2GB+ heap memory (pre-configured in gradle.properties) |
| 80 | +- **Network Dependencies**: Initial builds require internet access for dependency resolution |
| 81 | +- **Platform-specific builds**: Some targets may be disabled on certain OS (use `--continue` flag) |
| 82 | + |
| 83 | +## Project Architecture and Layout |
| 84 | + |
| 85 | +### Module Structure |
| 86 | +``` |
| 87 | +├── common/ # Core APIs, layouts, modifiers (foundation equivalent) |
| 88 | +├── material-icons-core/ # Icon system core |
| 89 | +├── material2/ # Material Design 2 components |
| 90 | +├── material3/ # Material Design 3 components |
| 91 | +├── navigation/ # Navigation support (experimental) |
| 92 | +├── lifecycle-viewmodel/ # ViewModel support (experimental) |
| 93 | +├── demo/ # Demonstration application |
| 94 | +└── buildSrc/ # Build configuration and dependencies |
| 95 | +``` |
| 96 | + |
| 97 | +### Key Configuration Files |
| 98 | +- **buildSrc/src/main/kotlin/VersionsAndDependencies.kt**: All dependency versions |
| 99 | +- **buildSrc/src/main/kotlin/common-conventions.gradle.kts**: Shared build configuration |
| 100 | +- **buildSrc/src/main/kotlin/lib-conventions.gradle.kts**: Library-specific configuration |
| 101 | +- **gradle.properties**: JVM memory settings for Gradle (increase if OOM occurs) and Kotlin MPP configuration |
| 102 | +- **settings.gradle.kts**: Project structure and repository configuration |
| 103 | + |
| 104 | +### Source Set Structure (Per Module) |
| 105 | +``` |
| 106 | +src/ |
| 107 | +├── commonMain/ # Shared APIs across all platforms |
| 108 | +├── composeUiMain/ # Compose UI targets (JVM, Android, iOS, Wasm) |
| 109 | +├── composeUiExceptAndroidMain/ # Compose UI excluding Android |
| 110 | +├── androidMain/ # Android-specific implementations |
| 111 | +├── jsMain/ # JS DOM implementations (Kobweb/HTML) |
| 112 | +├── jvmMain/ # Desktop JVM implementations |
| 113 | +└── iosMain/ # iOS-specific implementations |
| 114 | +``` |
| 115 | + |
| 116 | +### Dependencies and External Integration |
| 117 | + |
| 118 | +#### Required External Repositories |
| 119 | +```kotlin |
| 120 | +repositories { |
| 121 | + mavenCentral() |
| 122 | + google() // For Android components |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +**Note**: All dependencies are available from standard repositories. If working with snapshot dependencies of other `com.huanshankeji` libraries, additional setup may be required as per organization instructions. |
| 127 | + |
| 128 | +#### Key Dependencies |
| 129 | +- **Kotlin**: 2.2.20 with Compose Compiler |
| 130 | +- **Compose Multiplatform**: 1.9.0 |
| 131 | +- **Android Gradle Plugin**: 8.11.2 |
| 132 | +- **Kobweb**: 0.23.3 (now on Maven Central) |
| 133 | +- **Compose HTML Material**: 0.4.1-SNAPSHOT |
| 134 | +- **Binary Compatibility Validator**: 0.18.1 (enabled) |
| 135 | + |
| 136 | +### Platform-Specific Implementation Patterns |
| 137 | + |
| 138 | +#### Compose UI Platforms (Android, JVM, iOS, Wasm) |
| 139 | +- Delegate directly to official `androidx.compose` APIs |
| 140 | +- Located in `composeUiMain` source sets |
| 141 | + |
| 142 | +#### JS DOM Platform |
| 143 | +- Built on **Kobweb Silk** (provides Modifier system and layouts) |
| 144 | +- Uses **Material Web Components** via Compose HTML Material |
| 145 | +- Located in `jsMain` source sets |
| 146 | +- Requires CSS imports for Material Icons |
| 147 | + |
| 148 | +### Development Patterns and Conventions |
| 149 | + |
| 150 | +#### API Structure |
| 151 | +- **Common APIs**: Defined in `commonMain`, expect/actual pattern for platform differences |
| 152 | +- **Ext Components**: Components in `ext` packages don't follow androidx.compose APIs exactly but provide more idiomatic platform-specific wrappers |
| 153 | +- **Parameter Naming**: Parameters with "JsDom" or "ComposeUi" suffixes are platform-specific |
| 154 | + |
| 155 | +#### Code Quality and Validation |
| 156 | +- **Binary Compatibility**: Enforced via org.jetbrains.kotlinx.binary-compatibility-validator plugin |
| 157 | +- **Limited Testing**: Project acknowledges "limited number of tests" |
| 158 | + |
| 159 | +**Code Style:** |
| 160 | +- Follow [our Kotlin code style guide](https://github.com/huanshankeji/.github/blob/main/kotlin-code-style.md) for all Kotlin code contributions |
| 161 | + |
| 162 | +#### Architecture Notes |
| 163 | +- **Multi-module**: Each feature area is a separate Gradle subproject |
| 164 | +- **Expect/Actual Pattern**: Platform-specific implementations using Kotlin Multiplatform patterns |
| 165 | +- **Convention Plugins**: Custom build logic in `buildSrc` for consistency across modules |
| 166 | +- **Target Platforms**: Sophisticated setup targeting 6+ platforms with different implementation strategies |
| 167 | + |
| 168 | +### Root Directory Files |
| 169 | +``` |
| 170 | +.gitignore # Standard exclusions plus .kotlin, local.properties |
| 171 | +build.gradle.kts # Root build file with binary compatibility validator |
| 172 | +CHANGELOG.md # Detailed version history with breaking changes |
| 173 | +CODE_OF_CONDUCT.md # Standard code of conduct |
| 174 | +CONTRIBUTING.md # Development guidelines and contribution process |
| 175 | +gradle.properties # Memory settings and Kotlin configuration |
| 176 | +LEGACY_README.md # Previous project name reference |
| 177 | +LICENSE # Apache 2.0 license |
| 178 | +README.md # Comprehensive API documentation and usage guide |
| 179 | +settings.gradle.kts # Project structure and dependency management |
| 180 | +``` |
| 181 | + |
| 182 | +## Validation Steps for Changes |
| 183 | + |
| 184 | +1. **Build Validation**: Run `./gradlew build` or `./gradlew publishToMavenLocal` to ensure libraries compile |
| 185 | +2. **Test Validation**: Run `./gradlew check` to validate existing tests pass |
| 186 | +3. **Demo Validation**: Build demo with `./gradlew :compose-multiplatform-html-unified-demo:sideBySideBrowserDistribution` |
| 187 | +4. **CI Simulation**: Test on multiple platforms if possible (the CI runs on Ubuntu, macOS, Windows) |
| 188 | +5. **Binary Compatibility**: The kotlinx binary compatibility validator will catch API breaks |
| 189 | + |
| 190 | +## Important Notes for Agents |
| 191 | + |
| 192 | +- **Trust These Instructions**: Only perform additional searches if information here is incomplete or incorrect |
| 193 | +- **Network Dependency**: Initial builds require internet access for dependency resolution |
| 194 | +- **Memory Requirements**: Ensure adequate memory for Wasm compilation (2GB JVM heap configured) |
| 195 | +- **Limited Test Coverage**: Don't expect comprehensive test suites - focus on build and demo validation |
| 196 | +- **Platform Complexity**: This is a sophisticated multiplatform project with 6+ target platforms and complex expect/actual patterns |
| 197 | + |
| 198 | +**Trust these instructions**: This information has been validated through actual command execution and file inspection. Only search for additional information if these instructions are incomplete or found to be incorrect. |
0 commit comments