# Kromium

> Kromium is an open-source, production-grade embedded Chromium browser engine tailored for Compose Multiplatform Desktop and Kotlin JVM applications. Powered by Chromium Embedded Framework (CEF 150) with automated Windows Registry write suppression, anti-telemetry, enterprise proxy strategies, zero-dependency headless browsing, hardware acceleration (JAWT/Skiko), and idiomatic Kotlin coroutine APIs.

Website: https://kromium.daviante.dev/
Repository: https://github.com/daviantegroup/kromium
Maven Central: dev.daviante:kromium-compose:2.1.150-b11
License: Apache-2.0

## Quick Start

### 1. Gradle Dependency
```kotlin
// build.gradle.kts
dependencies {
    implementation("dev.daviante:kromium-compose:2.1.150-b11")
}
```

> [!NOTE]
> Version `2.1.150-b11` is the official **Latest Stable** release. Version `2.0.150-b11` is designated as **Previous Stable**, and `1.2.150-b11` is **Legacy Stable**. Older builds (`1.1.150-b11`, `1.0.150-b11`, `1.0.150`) are pre-test builds not recommended for production.

### 2. Basic Compose Desktop Browser
```kotlin
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import dev.daviante.kromium.compose.KromiumView
import dev.daviante.kromium.compose.rememberKromiumState

@Composable
fun App() {
    val state = rememberKromiumState("https://github.com")
    KromiumView(
        state = state,
        modifier = Modifier.fillMaxSize()
    )
}
```

## Core API Reference

- `Kromium`: Singleton engine lifecycle controller. Call `Kromium.initialize(config)` before UI rendering and `Kromium.dispose()` upon application exit. Provides `createBrowser()`, `createHeadlessBrowser()`, and dynamic runtime proxy switching via `setProxy(proxy)`.
- `rememberKromiumState(initialUrl)`: Composable state holder tracking current URL, loading state, title, asset filtering (`assetFilter`, `blockMediaAssets`), host-locking (`setHostLock`, `clearHostLock`), and download callbacks.
- `KromiumView(state, modifier, client, loadingContent)`: Desktop Composable embedding the Chromium viewport via hardware-accelerated Skiko / JAWT surfaces with an optional loading slot.
- `KromiumConfig`: Engine configuration builder controlling cache quarantine (`--root-cache-path`, `--user-data-dir`), Windows Registry write suppression (`blockRegistryAndTelemetry = true`), SSO allowlists (`authServerAllowlist`, `authNegotiateDelegateAllowlist`), remote debugging port, proxy settings, and GPU acceleration flags.
- `KromiumProxy`: Enterprise proxy sealed class supporting 7 strategies: `System`, `Direct`, `AutoDetect` (WPAD), `Pac`, `Http`/`Https` with TLS tunneling and bypass lists, `Socks5` with remote DNS resolution, and `MultiProtocol`. Supports dynamic runtime switching and HTTP 407 proxy authentication fallbacks.
- `KromiumAssetFilter`: Type-safe resource filter controlling download of images, audio/video media, web fonts, and stylesheets with `ALL_BLOCKED` and `MEDIA_ONLY` presets.
- `KromiumClient`: Native browser instance exposing `evaluateJavaScript`, `getCookies`, `injectHeaders`, devtools inspection, download controls (`cancelDownload`, `pauseDownload`, `resumeDownload`), dynamic `setProxy`, `hostLock`, `assetFilter`, and composite handler multiplexing.
- `JvmModuleOpener`: Dynamically opens internal `java.desktop/sun.awt` modules on Java 17 and 21+ at runtime via Unsafe and MethodHandles reflection, enabling zero-config desktop startup without `--add-opens` flags.

## Documentation Index

- [Overview](https://kromium.daviante.dev/#/docs/overview): High-level architecture, supported platforms (Windows, macOS Intel/ARM, Linux), and capabilities.
- [Release & Version History](https://kromium.daviante.dev/#/docs/version-history): Certified release matrix, build channels (Stable, Previous Stable, Pre-Test), and upgrade guides.
- [What's New in v2.1.150-b11](https://kromium.daviante.dev/#/docs/whats-new): CodeQL CWE-022/CWE-073 path traversal remediation, enterprise proxy strategies, Windows registry suppression, and headless browsing.
- [Prerequisites & System Requirements](https://kromium.daviante.dev/#/docs/prerequisites): JDK 17+, OS compatibility matrix, and graphics drivers.
- [Installation & Gradle Setup](https://kromium.daviante.dev/#/docs/installation): Maven Central artifacts, Multiplatform sourceSets, and ProGuard rules.
- [Your First Compose Desktop Browser](https://kromium.daviante.dev/#/docs/first-browser): Step-by-step tutorial for building a desktop browser window.
- [KromiumView Composable](https://kromium.daviante.dev/#/docs/compose-view): Viewport embedding, sizing, loadingContent slots, and event handling in Compose Multiplatform.
- [Browser State & Lifecycle](https://kromium.daviante.dev/#/docs/compose-state): Managing loading state, title observation, host-locking, and back/forward history.
- [Navigation & History](https://kromium.daviante.dev/#/docs/compose-navigation): Programmatic navigation, URL reloading, and history traversal.
- [Zoom & Display Settings](https://kromium.daviante.dev/#/docs/compose-zoom): HiDPI scaling, zoom level adjustments, and dark mode emulation.
- [JavaScript Bridge & Coroutines](https://kromium.daviante.dev/#/docs/js-bridge): Non-blocking JS evaluation with Kotlin coroutines (`evaluateJavaScript<T>`).
- [DOM Content & Media Extraction](https://kromium.daviante.dev/#/docs/dom-extraction): HTML extraction, screenshot capturing, and element inspection.
- [Network Interception & Headers](https://kromium.daviante.dev/#/docs/network-interception): Request filtering, custom header injection, and response body inspection.
- [Proxy Configuration](https://kromium.daviante.dev/#/docs/proxy-configuration): Enterprise proxy strategies (System, Direct, WPAD, PAC, HTTP/S, SOCKS5), dynamic switching, and HTTP 407 auto-auth.
- [Asset Filtering & Scoped SSL Policies](https://kromium.daviante.dev/#/docs/asset-filtering): Resource blocking with KromiumAssetFilter, host locking, and scoped SSL policies.
- [Headless Browsing & Automation](https://kromium.daviante.dev/#/docs/headless-automation): Zero-dependency off-screen headless browsing, web scraping, PDF generation, and click simulation.
- [Cookie Management](https://kromium.daviante.dev/#/docs/cookie-management): Persistent cookie jars, session extraction, and domain cookie filtering.
- [DevTools & Console Capture](https://kromium.daviante.dev/#/docs/devtools-console): Capturing console.log messages and remote Chrome DevTools debugging.
- [Dialogs & Downloads](https://kromium.daviante.dev/#/docs/dialogs-downloads): Handling JavaScript alert/confirm/prompt dialogs and file downloads.
- [Swing Embedding](https://kromium.daviante.dev/#/docs/swing-embedding): Using Kromium in legacy Java Swing or JavaFX desktop applications.
- [Swing Lifecycle](https://kromium.daviante.dev/#/docs/swing-lifecycle): Event dispatch thread (EDT) safety and component repainting.
- [Threading Model & Dispatchers](https://kromium.daviante.dev/#/docs/threading-model): UI thread vs CEF message loop dispatching.
- [Native Binary Extraction & Cache](https://kromium.daviante.dev/#/docs/native-binaries): Automatic binary extraction and multiplatform caching mechanics.
- [Security & Sandboxing](https://kromium.daviante.dev/#/docs/security-sandboxing): CodeQL CWE-022/CWE-073 path injection remediation, filesystem root boundary enforcement, Windows registry write suppression, and process sandboxing.
- [Engine Termination & Disposal](https://kromium.daviante.dev/#/docs/shutdown-disposal): Clean shutdown sequence to prevent zombie processes and memory leaks.
- [Troubleshooting Common Issues](https://kromium.daviante.dev/#/docs/troubleshooting): Resolving black screen issues, missing DLLs, and font rendering.
- [FAQ](https://kromium.daviante.dev/#/docs/faq): Frequently asked questions regarding licensing, performance, and memory usage.
- [Privacy Policy](https://kromium.daviante.dev/#/docs/privacy-policy): Zero telemetry disclosures and data handling.
- [Terms of Use](https://kromium.daviante.dev/#/docs/terms-of-use): Open source software licensing and code sample reuse permissions.

## Full Concatenated Documentation
For autonomous coding agents needing all documentation in a single file:
https://kromium.daviante.dev/llms-full.txt