# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an IntelliJ IDEA plugin that provides Slint language support through LSP (Language Server Protocol) integration. The plugin downloads platform-specific Slint LSP binaries from GitHub releases and integrates them with IntelliJ's LSP infrastructure.

## Build System

This project uses Gradle with the Kotlin DSL and the IntelliJ Platform Gradle Plugin.

### Common Commands

**Build the plugin:**
```bash
./gradlew build
```

**Run the plugin in a sandbox IDE:**
```bash
./gradlew runIde
```

**Run tests:**
```bash
./gradlew test
```

**Verify plugin compatibility:**
```bash
./gradlew verifyPlugin
```

**Build plugin distribution ZIP:**
```bash
./gradlew buildPlugin
```

**Clean build artifacts:**
```bash
./gradlew clean
```

## Architecture

### LSP Integration

The plugin uses IntelliJ's LSP support (`com.intellij.modules.lsp`) to provide language features for `.slint` files.

**Key components:**

- `SlintLspServerSupportProvider` (src/main/kotlin/me/zhouxi/slint/lsp/SlintLspServerSupportProvider.kt:13): Main LSP integration point. Implements `LspServerSupportProvider` to start the Slint LSP server when `.slint` files are opened.

- `SlintRuntime` (src/main/kotlin/me/zhouxi/slint/SlintRuntime.kt:8): Manages plugin paths and locates the platform-specific LSP binary. Detects OS (Windows/Linux/macOS) and resolves the correct executable path.

- `FooLspServerDescriptor` (src/main/kotlin/me/zhouxi/slint/lsp/SlintLspServerSupportProvider.kt:34): Internal descriptor that creates the command line for launching the LSP server.

### Binary Distribution

The build process downloads platform-specific Slint LSP binaries from GitHub releases:

- **Download task** (build.gradle.kts:72-79): Downloads LSP binaries for Linux, macOS, and Windows from `https://github.com/slint-ui/slint/releases/download/v{version}/`

- **Extract task** (build.gradle.kts:80-104): Extracts and renames binaries to standardized names (`slint-lsp-linux`, `slint-lsp-macos`, `slint-lsp-windows.exe`)

- **Sandbox preparation** (build.gradle.kts:105-111): Copies extracted binaries to `slint/lsp/` directory in the plugin sandbox

The Slint version is configured in `gradle.properties` via the `slintVersion` property.

### Plugin Configuration

- **plugin.xml** (src/main/resources/META-INF/plugin.xml): Declares the plugin metadata, dependencies, and extension points. Registers `SlintLspServerSupportProvider` as the LSP server support provider.

- **Target IDE version**: IntelliJ IDEA 2025.2.4 with minimum build 252.25557 (configured in build.gradle.kts:43,56)

- **Java/Kotlin version**: JVM 21 (build.gradle.kts:68-70,114-118)

## Project Structure

```
src/main/kotlin/me/zhouxi/slint/
├── SlintRuntime.kt              # Plugin runtime and binary path resolution
├── icons/SlintIcons.kt          # Icon resources for UI
└── lsp/
    └── SlintLspServerSupportProvider.kt  # LSP integration
```

## Testing the Plugin

### Manual Testing

1. **Build and run in sandbox:**
   ```bash
   ./gradlew runIde
   ```

2. **Test with sample file:**
   - Open `test-files/hello.slint`
   - Verify file icon, syntax highlighting, and LSP features

3. **Test LSP features:**
   - Code completion: Type and press Ctrl+Space
   - Goto definition: Ctrl+Click on symbols
   - Hover: Mouse over symbols
   - Diagnostics: Introduce syntax errors
   - Formatting: Ctrl+Alt+L

### Verify LSP Server

Check LSP server status in the status bar (bottom right). Should show "Slint" when a .slint file is open.

### Common Issues

- **LSP server not starting**: Check that LSP binary exists in sandbox at `sandbox/plugins/slint/lsp/slint-lsp-{platform}`
- **No syntax highlighting**: Verify TextMate grammar file is in resources
- **No completion**: Check LSP server logs in `idea.log`

## Development Notes

- The plugin uses IntelliJ's built-in LSP client infrastructure, so language features (completion, diagnostics, etc.) are provided by the Slint LSP server itself.

- The sandbox directory is configured to `sandbox/` in the project root (build.gradle.kts:53).

- When modifying LSP integration, test by running `./gradlew runIde` which launches a sandbox IDE with the plugin installed.

- To update the Slint LSP version, change `slintVersion` in `gradle.properties` and rebuild. The build will download new binaries automatically.