# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
`app_input` is a cross-platform library for receiving raw keyboard and mouse events. It provides a unified API across Windows, macOS, Linux, and WebAssembly platforms.
## Build Commands
### Rust (Native)
```bash
# Build the library
cargo build
# Run the example application
cargo run --example main
# Run tests
cargo test
# Generate documentation
cargo doc --open
# Check code without building
cargo check
# Run clippy linter
cargo clippy
```
### WebAssembly
```bash
# Build WASM package (from project root)
wasm-pack build
# Run WASM example (requires wasm-server-runner)
cargo run --example main --target wasm32-unknown-unknown
```
### Swift (macOS only)
```bash
# Build Swift package (automatic via build.rs on macOS)
cd SwiftRawInput && swift build
# Run Swift tests
cd SwiftRawInput && swift test
```
## Architecture
### Platform Abstraction
The library uses a trait-based approach with platform-specific implementations:
- Each platform implements `PlatformKeyboard` and `PlatformMouse` traits
- Platform selection happens at compile time via conditional compilation
- State is managed using atomic operations for thread safety
### Key Components
- `src/keyboard.rs` and `src/mouse.rs`: Public API and platform dispatch
- `src/keyboard/{platform}.rs`: Platform-specific keyboard implementations
- `src/mouse/{platform}.rs`: Platform-specific mouse implementations
- `SwiftRawInput/`: Swift package for macOS AppKit integration
- `build.rs`: Handles Swift compilation and linking on macOS
### Platform Integration Requirements
- **Windows/Linux**: Requires manual integration with native event loop (see README)
- **macOS**: Works automatically via NSApplication
- **WASM**: Works automatically in browser context
### Coordinate System
All platforms use a unified coordinate system with origin at upper-left corner of the primary display.
## Development Notes
- The library follows a "zero-magic" philosophy - no hidden event loops or threads
- All platform code is behind feature flags for conditional compilation
- Mouse coordinates are normalized across all platforms
- Keyboard events are hardware-based (scan codes), not character-based
- The Swift bindings use a custom FFI bridge generated by build.rs