dev server improvement

Author: xpenatan

AGENTS.md

@@ -54,7 +54,7 @@
 - Dependency aliases and dependency, plugin, release, and snapshot versions are centralized in
   `gradle/libs.versions.toml`.
 - Local source paths and composite-build switches remain in `gradle.properties`.
-- Root `build.gradle.kts` applies shared Java 11 settings and Maven repositories to subprojects.
+- Root `build.gradle.kts` applies shared Java 17 settings and Maven repositories to subprojects.
 - `gradle.properties` can enable composite builds for local libGDX or TeaVM source:
   - `includeLibgdxSource`
   - `includeTeaVMSource`

README.md

@@ -16,7 +16,7 @@ The project provides two build styles:
 | gdx-teavm | libGDX | TeaVM  |
 |:---------:|:------:|:------:|
 | -SNAPSHOT | 1.14.2 | 0.15.0 |
-|   1.6.0   | 1.14.2 | 0.15.0 |
+|   1.6.1   | 1.14.2 | 0.15.0 |
 |   1.5.5   | 1.14.0 | 0.14.0 |
 |   1.5.4   | 1.14.0 | 0.13.1 |
 
@@ -43,40 +43,17 @@ The project provides two build styles:
 - [Examples](examples/README.md): portable cores and runnable platform implementations.
 - [Desktop C native build guide](examples/basic/platforms/desktop/teavm-c/builder/README.md): native toolchain requirements and manual CMake workflow.
 
-## Repositories
+## Setup
 
-Release artifacts are published to Maven Central. Snapshots are published to Central Portal snapshots.
-
-```kotlin
-repositories {
-    mavenCentral()
-    maven("https://central.sonatype.com/repository/maven-snapshots/")
-
-    // TeaVM artifacts may be needed while using TeaVM snapshots or non-central builds.
-    maven("https://teavm.org/maven/repository/")
-}
-```
-
-When using the Gradle plugin from Maven, add the same repositories to `pluginManagement` in `settings.gradle.kts`.
-
-```kotlin
-pluginManagement {
-    repositories {
-        mavenCentral()
-        maven("https://central.sonatype.com/repository/maven-snapshots/")
-    }
-}
-```
-
-The gdx-teavm plugin marker is published to Maven with the rest of the artifacts, so Gradle Plugin Portal is not required for this plugin.
+Release artifacts are available from Maven Central. Snapshot and plugin repository configuration is documented once in the [usage guide](docs/usage.md#repositories).
 
 ## Gradle Plugin Quick Start
 
 Apply the plugin in the TeaVM target module:
 
 ```kotlin
 plugins {
-    id("com.github.xpenatan.gdx-teavm") version "-SNAPSHOT"
+    id("com.github.xpenatan.gdx-teavm") version "<latest-release>"
 }
 
 dependencies {
@@ -111,51 +88,11 @@ For native targets and every available property, see the [usage guide](docs/usag
 
 ## Manual Builder Quick Start
 
-Use the builder API when you need full programmatic control or a custom build launcher. See the [usage guide](docs/usage.md) for complete builder examples.
-
-```kotlin
-dependencies {
-    implementation("com.github.xpenatan.gdx-teavm:backend-web:-SNAPSHOT")
-    implementation(project(":core"))
-}
-```
-
-Run the Java launcher from Gradle or your IDE. Builder projects add the concrete backend dependency they use, such as `backend-web` or `backend-glfw`.
+Use the builder API when you need full programmatic control or a custom build launcher. The [manual builder guide](docs/usage.md#manual-builder-api) contains dependencies and complete Web and GLFW examples.
 
 ## Examples In This Repository
 
-```shell
-# Plugin workflow
-./gradlew :examples:basic:platforms:web:plugin:gdx_teavm_web_js_run
-./gradlew :examples:basic:platforms:web:plugin:gdx_teavm_web_wasm_run
-./gradlew :examples:basic:platforms:desktop:teavm-c:plugin:gdx_teavm_glfw_generate
-./gradlew :examples:basic:platforms:ios:gdx_teavm_ios_generate
-./gradlew :examples:basic:platforms:ios:gdx_teavm_ios_init_xcode
-
-# Android TeaVM C examples
-./gradlew :examples:basic:platforms:android:assembleDebug
-./gradlew :examples:freetype:platforms:android:assembleDebug
-./gradlew :examples:controllers:platforms:android:assembleDebug
-
-# iOS TeaVM C examples (simulator builds require macOS)
-./gradlew :examples:basic:platforms:ios:gdx_teavm_ios_build_simulator
-./gradlew :examples:freetype:platforms:ios:gdx_teavm_ios_build_simulator
-./gradlew :examples:controllers:platforms:ios:gdx_teavm_ios_build_simulator
-
-# FreeType plugin workflow
-./gradlew :examples:freetype:platforms:web:plugin:gdx_teavm_web_js_run
-./gradlew :examples:freetype:platforms:web:plugin:gdx_teavm_web_wasm_run
-
-# gdx-controllers plugin workflow
-./gradlew :examples:controllers:platforms:web:plugin:gdx_teavm_web_js_run
-./gradlew :examples:controllers:platforms:web:plugin:gdx_teavm_web_wasm_run
-
-# Manual builder workflow
-./gradlew :examples:basic:platforms:web:builder:basic_web_run
-./gradlew :examples:freetype:platforms:web:builder:freetype_web_run
-./gradlew :examples:controllers:platforms:web:builder:controllers_web_run
-./gradlew :examples:basic:platforms:desktop:teavm-c:builder:basic_desktop_c_debug_build
-```
+The [examples index](examples/README.md) describes the project layout and links to the task inventory for each example.
 
 ## Support
 

docs/backend-architecture.md

@@ -60,19 +60,13 @@ Android projects use a dedicated path instead: the Android Gradle Plugin remains
 
 Target blocks are opt-in. If a build file declares only `wasm {}`, only Wasm gdx-teavm tasks are created. Native TeaVM C settings live inside target blocks such as `glfw {}` because logical targets can have different launchers and native options. Android projects currently support only the `android {}` target.
 
-## Gradle Plugin Tasks
+## Gradle Task Integration
 
-| Target block | Tasks |
-| --- | --- |
-| `js {}` | `gdx_teavm_web_js_build`, `gdx_teavm_web_js_run` |
-| `wasm {}` | `gdx_teavm_web_wasm_build`, `gdx_teavm_web_wasm_run` |
-| `glfw {}` | `gdx_teavm_glfw_generate`, `gdx_teavm_glfw_build`, `gdx_teavm_glfw_run` |
-| `ios {}` | `gdx_teavm_ios_generate`, `gdx_teavm_ios_prepare_angle`, `gdx_teavm_ios_init_xcode`, `gdx_teavm_ios_regenerate_xcode`, `gdx_teavm_ios_open_xcode`, `gdx_teavm_ios_build_simulator`, `gdx_teavm_ios_run_simulator` |
-| `android {}` | `gdx_teavm_android_generate` |
+Each declared target registers only its own public `gdx_teavm_*` tasks. The [usage guide](usage.md#web-targets) is the user-facing task reference; this section covers the implementation behind web run tasks.
 
-Web run tasks use `GdxTeaVMRunWebTask` by default, loading `backend-web`'s `JettyServer` by reflection from the target runtime classpath. When the target's `devServer.enabled` property is true, the same public run task delegates compilation to TeaVM's `javaScriptDevServer` or `wasmGCDevServer` task. With `autoBuild` enabled, the run task registers a Gradle `DeploymentHandle`; Gradle detects that reloadable deployment, automatically enters continuous-build mode for the same invocation, and reruns Java compilation and TeaVM generation when task inputs change. With `autoBuild` disabled, the task blocks directly to keep both servers alive without registering a reloadable deployment. Local project class directories precede external JARs on the development classpath so TeaVM observes recompiled classes, and the plugin invalidates TeaVM's compiler cache before each rebuild. Cancelling the overall Gradle invocation stops both the TeaVM server and entry adapter in either mode.
+Web run tasks use `GdxTeaVMRunWebTask` and `backend-web`'s `JettyServer` unless `devServer.enabled` selects the TeaVM server. In development-server mode, the public run task starts TeaVM compilation, an entry-page adapter, and an optional file watcher. The watcher invokes only the target project's `classes` task, then requests an incremental build from the existing TeaVM process. Local project output directories precede external JARs so the compiler sees the updated classes.
 
-The entry adapter supplies the generated page at `/` with an HTML content type, working around TeaVM serving generated `.html` files as plain text. When `autoReload` is enabled, it also installs a shared JS/Wasm client for TeaVM's build-status WebSocket. The plugin applies the same backend-filtered classpath and gdx-teavm properties to normal generation and development-server compilation.
+The entry adapter serves the generated page as HTML at `/`. With `autoReload` enabled, it also injects a JS/Wasm client for TeaVM's build-status WebSocket. Cancelling the run task stops both servers and releases the public port.
 
 ## TeaVM Runtime Plugins
 
@@ -200,14 +194,4 @@ This is required for facade/helper types such as DOM extension wrappers and `Web
 
 ## Output Layout
 
-Plugin defaults:
-
-| Target | Root | Generated files |
-| --- | --- | --- |
-| JS | `build/dist/js` | `webapp` |
-| Wasm | `build/dist/wasm` | `webapp` |
-| GLFW | `build/dist/glfw` | `c/src`, `c/release`, build scripts |
-| iOS | `build/dist/ios` | `c/src`, `c/release`, generated Xcode project |
-| Android | `build/generated/gdx-teavm/android` | `c/src`, `CMakeLists.txt`, native resources |
-
-Builder defaults depend on the `build(new File(...))` output directory and the concrete backend. `WebBackend` defaults to a `webapp` folder, while `TeaGLFWBackend` defaults to `c/src` plus `c/release`.
+Plugin defaults are maintained in the [property reference](plugin-properties.md#common-teavm-target-properties). Builder output is rooted at the directory passed to `build(File)` and organized by the concrete backend.