Auto Update

Author: andrestubbe

docs/PHILOSOPHY.md

@@ -1,26 +1,27 @@
 # The Philosophy of FastGhostMouse
 
 > [!IMPORTANT]
-> **"Visual Feedback without Interference. Zero Focus Theft. Absolute Click-Through."**
+> **"Visual feedback without interference: zero focus theft, absolute click-through, and zero AWT lag."**
 
-FastGhostMouse is built on the principle that automation bots, AI models, and testing frameworks desperately need visual debugging, but traditional Java UI solutions destroy the very environment they try to automate.
+FastGhostMouse is built on the fundamental principle that robotics bots, autonomous AI models, and testing frameworks require visual debugging, but traditional Java UI solutions degrade or destroy the target environment.
 
 ## Core Tenets
 
-1.  **Do Not Disturb the Host**
-    An automation overlay must never steal focus (`WS_EX_NOACTIVATE`) and must never block input (`WS_EX_TRANSPARENT`). If a bot clicks, the click must reach the target app, not the overlay.
+### 1. Do Not Disturb the Host
+An automation overlay must never steal window focus (`WS_EX_NOACTIVATE`) and must never capture or block mouse input (`WS_EX_TRANSPARENT`). When a user or bot clicks, the hardware event must reach the underlying window, not the overlay.
 
-2.  **Bypass the AWT/Swing EDT**
-    Standard Java windows (`JFrame`) are bound to the Event Dispatch Thread. Tying your bot's visual feedback to the heavy AWT pipeline guarantees micro-stutters and input lag. FastGhostMouse hooks directly into native Win32/DWM rendering to bypass Java's UI constraints entirely.
+### 2. Bypass the Java AWT Event Dispatch Thread (EDT)
+Standard Java UI components (`JFrame`, `JWindow`, `JDialog`) are bound to AWT's single-threaded EDT. Running high-frequency cursor animations on the EDT causes micro-stuttering, GC pressure, and input latency. FastGhostMouse runs its interpolation loop on a dedicated lightweight thread, driving DirectComposition native surfaces directly via `FastOverlay`.
 
-3.  **Visual Truth for AI**
-    When training or debugging AI agents, seeing the *exact* intended path of the cursor is critical. FastGhostMouse interpolates natively to show smooth trajectories and state changes, giving developers an instant "window into the AI's mind."
+### 3. Visual Transparency for Autonomous Agents
+When training or debugging AI agents, observing the exact planned and smoothed trajectory is critical. FastGhostMouse interpolates motion continuously and renders state tags, giving developers immediate visual inspection of AI intentions without interfering with vision capture pipelines like `FastScreen`.
 
-4.  **Blueprint Consistency**
-    As part of the **FastJava** ecosystem, FastGhostMouse adheres to a standardized architecture:
-    *   **Native Backend**: Direct C++ implementation via `FastOverlay`.
-    *   **Unified Loading**: Powered by `FastCore`.
-    *   **Premium Quality**: Built specifically for high-performance automation and autonomous agents.
+### 4. Ecosystem Synergy
+FastGhostMouse is designed to compose cleanly with the FastJava substrate:
+* **Render Pipeline**: Built directly on `FastOverlay` for DirectComposition transparency.
+* **Input Injection**: Integrates with `FastRobot` for native Win32 `SendInput` automation.
+* **JNI Substrate**: Native libraries resolved and loaded seamlessly via `FastCore`.
 
 ---
-**❤️ FastGhostMouse — Powering the next generation of Native Java.**
+
+Part of the **FastJava** ecosystem. Clean architectures, zero EDT lag, maximum speed.

docs/REFERENCE.md

@@ -1,26 +1,88 @@
 # FastGhostMouse Reference
 
-## 1. Native Overlay Engine
-*   **WS_EX_TRANSPARENT**: The overlay window is mathematically ignored by the Windows input subsystem. Mouse clicks and keyboard events pass directly through to the underlying application.
-*   **WS_EX_NOACTIVATE**: The overlay will never steal window focus from your active game, application, or browser, ensuring automation bots are not interrupted.
-*   **WS_EX_LAYERED**: Enables per-pixel alpha transparency and high-performance image blending via standard Windows APIs.
-
-## 2. API Capabilities
-*   **useAsSecondaryMouse(x, y, index)**: Captures the active Windows cursor and seamlessly integrates it into a secondary, scriptable hardware cursor.
-*   **moveTo(x, y)**: Initiates a hardware-accelerated, interpolated movement to the target coordinates.
-*   **setSmoothing(factor)**: Adjusts the momentum and easing of the cursor. Lower values produce heavier, more human-like drag, while higher values snap instantly.
-*   **setTextImage**: Attaches dynamic visual text or labels directly beneath the cursor (e.g., "Executing AI Action").
-
-## 3. FastCore & FastOverlay Bindings
-*   **JNI Hooks**: `FastGhostMouse` relies on the unified `FastCore` JNI loader to access `FastOverlayWindow` instances.
-*   **Zero Swing/AWT Logic**: The overlay bypasses the Java Event Dispatch Thread (EDT) completely, preventing UI locks or stutters during complex bot logic.
-
-## 4. Platform Support
-| Platform | Status |
-|----------|--------|
-| Windows 10/11 (x64) | ✅ Fully Supported |
-| Linux | 🚧 Planned (X11/Wayland hooks) |
-| macOS | 🚧 Planned |
+## 1. Native Architecture & Subsystems
+
+`FastGhostMouse` provides a hardware-accelerated, transparent ghost cursor overlay for AI agent trajectory visualization, automation debugging, and bot telemetry.
+
+It directly composites two native `FastOverlayWindow` surfaces via DirectComposition / DWM:
+1. **Cursor Window**: Renders either a custom high-DPI `BufferedImage` or the captured Windows OS hardware cursor (`captureSystemCursor()`).
+2. **Text Label Window**: Renders dynamic HUD status text or AI state labels directly offset next to the cursor without affecting OS hit testing.
+
+Both windows enforce the following Win32 styles:
+* `WS_EX_TRANSPARENT`: Mathematically transparent to the Windows input subsystem. Mouse and keyboard events pass directly to windows below.
+* `WS_EX_NOACTIVATE`: Never receives or steals window focus, guaranteeing target application continuity.
+* `WS_EX_LAYERED`: Sub-millisecond alpha blending and per-pixel transparency composited directly by the Desktop Window Manager (DWM).
 
 ---
-**Part of the FastJava Ecosystem** — *Making the JVM faster. Small package. Maximum speed. Zero bloat. 🚀📋*
+
+## 2. API Reference
+
+### `FastGhostMouse`
+
+| Method | Signature | Description | Native / Subsystem Call |
+|:---|:---|:---|:---|
+| `init(startX, startY)` | `void` | Spawns dual `FastOverlayWindow` handles at coordinates and starts the 120 FPS physics loop. | `FastOverlay.createWindow` |
+| `useAsSecondaryMouse(x, y, index)` | `void` | Spawns cursor, captures current OS hardware cursor, and displays overlay. | `captureSystemCursor()`, `show()` |
+| `moveTo(targetX, targetY)` | `void` | Sets target coordinates for smooth physics-based cursor interpolation. | Internal delta-time Euler integration |
+| `setCursorPositionImmediate(x, y)` | `void` | Instantly teleports the cursor overlay without animation delay. | `FastOverlayWindow.setPosition` |
+| `setSmoothing(factor)` | `void` | Configures momentum and easing responsiveness (default: `0.12f`). | Animation physics coefficient |
+| `setTextOffset(dx, dy)` | `void` | Configures pixel offset of the status label window relative to cursor tip. | Win32 layout translation |
+| `setCursorImage(img)` | `void` | Applies custom `BufferedImage` icon to the cursor overlay surface. | `FastOverlayWindow.updateImage` |
+| `setTextImage(img)` | `void` | Applies custom `BufferedImage` rendered label next to cursor. | `FastOverlayWindow.updateImage` |
+| `captureSystemCursor()` | `void` | Queries native Win32 `GetCursorInfo` and extracts current OS cursor bitmap. | `captureSystemCursorNative` (JNI) |
+| `setSystemCursorVisible(visible)` | `void` | Dynamically hides or restores the OS hardware cursor via Win32 `SetSystemCursor`. | `setSystemCursorVisible` (JNI) |
+| `show()` | `void` | Makes cursor and text overlays visible. | `FastOverlayWindow.show` |
+| `hide()` | `void` | Hides cursor and text overlays. | `FastOverlayWindow.hide` |
+| `dispose()` | `void` | Shuts down animation thread, releases overlay windows, and restores OS cursor. | Win32 handle cleanup |
+
+---
+
+### `FastGhostMouseBot`
+
+| Method | Signature | Description | Subsystem Call |
+|:---|:---|:---|:---|
+| `softPress(x, y)` | `void` | Injects low-latency virtual left mouse button down event. | `FastRobot.virtualMousePress` |
+| `softDrag(x, y)` | `void` | Dispatches continuous coordinate stream during active drag. | `FastRobot.virtualMouseMove` |
+| `softRelease(x, y)` | `void` | Injects virtual left mouse button release and resets drag state. | `FastRobot.virtualMouseRelease` |
+| `isDragging()` | `boolean` | Queries active drag state. | Internal boolean state |
+
+---
+
+## 3. Platform Support
+
+| Platform | Architecture | Status | Engine / Pipeline |
+|:---|:---|:---|:---|
+| **Windows 10 / 11** | `x64` | ✅ Fully Supported | Win32 Layered Windows + DirectComposition (`FastOverlay`) |
+| **Windows 10 / 11** | `arm64` | 🚧 Planned | Native Windows on ARM DirectComposition pipeline |
+| **Linux** | `x64` | 🚧 Planned | X11 Composite / Wayland Subsurface transparent overlay |
+| **macOS** | `x64` / `arm64` | 🚧 Planned | CoreGraphics / Metal Overlay Window |
+
+---
+
+## 4. Ecosystem Integration
+
+```
++-------------------------------------------------------------+
+|                 FastGhostMouse Application                  |
++-------------------------------------------------------------+
+                              |
+       +----------------------+----------------------+
+       |                                             |
+       v                                             v
++-----------------------------+       +-----------------------------+
+|         FastOverlay         |       |          FastRobot          |
+|  (DirectComposition Canvas) |       |   (Native Input Injection)  |
++-----------------------------+       +-----------------------------+
+       |                                             |
+       +----------------------+----------------------+
+                              |
+                              v
++-------------------------------------------------------------+
+|                          FastCore                           |
+|               (Native Library JNI Loader)                   |
++-------------------------------------------------------------+
+```
+
+---
+
+Part of the **FastJava** ecosystem. Clean architectures, zero EDT lag, maximum speed.

docs/ROADMAP.md

@@ -1,24 +1,24 @@
-# FastGhostMouse Roadmap 🗺️
+# FastGhostMouse Roadmap
 
-**Vision:** To provide the fastest possible native primitives for mouse input by aggressively bypassing bottlenecks in standard Java.
+**Vision:** High-performance, zero-latency ghost cursor and AI trajectory visualization for the JVM.
 
-## 🟢 v0.1.0: Initial Release (Current)
-- [x] **Core Native Engine**: Basic JNI implementation.
-- [x] **Blueprint Standards**: README, Reference, and Philosophy integration.
-- [ ] **Basic Performance Suite**: Initial benchmarks vs standard Java.
+## Current Milestone: v0.1.0 (Released)
+- [x] Standardized FastJava ecosystem architecture.
+- [x] DirectComposition GPU overlay integration via `FastOverlay`.
+- [x] Native hardware cursor capture and dynamic state labeling.
+- [x] Smooth physics-based cursor motion interpolation.
+- [x] Official JMH benchmark suite measuring throughput.
+- [x] Interactive window-repositioning demo (`examples/Demo`).
 
-## 🟡 v0.2.0: Optimization Phase
-- [ ] **SIMD Acceleration**: Implement AVX2/SSE4.2 paths for core loops.
-- [ ] **Software Prefetching**: Optimize memory access patterns.
-- [ ] **Alignment Enforcement**: Ensure zero-penalty memory boundaries.
+## Milestone: v0.2.0 (Performance & Vector Trails)
+- [ ] Hardware-accelerated motion trails (spline path drawing via Direct2D).
+- [ ] Multi-cursor support for parallel agent visualization.
+- [ ] Low-overhead coordinate ring buffer for telemetry recording.
 
-## 🟠 v0.5.0: Platform & Logic Expansion
-- [ ] **ARM NEON Port**: Parity for Apple Silicon/Mobile.
-- [ ] **Advanced Features**: Multi-threaded paths and complex batch operations.
-
-## 🔴 v1.0.0: Production Hardening
-- [ ] **Full Stability Audit**: Long-run stress testing.
-- [ ] **Enterprise Support**: NUMA-awareness and Large Pages support.
+## Milestone: v0.3.0 (Cross-Platform Foundations)
+- [ ] Linux X11 Composite & Wayland transparent subsurface prototypes.
+- [ ] macOS Metal-backed click-through window implementation.
 
 ---
-**Focus:** Performance is our USP. We optimize where Java stops.
+
+Part of the **FastJava** ecosystem. Clean architectures, zero EDT lag, maximum speed.

examples/Benchmark/dependency-reduced-pom.xml

@@ -69,9 +69,9 @@
   </dependencies>
   <properties>
     <jmh.version>1.37</jmh.version>
-    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <maven.compiler.target>17</maven.compiler.target>
+    <maven.compiler.target>21</maven.compiler.target>
     <uberjar.name>benchmarks</uberjar.name>
-    <maven.compiler.source>17</maven.compiler.source>
+    <maven.compiler.source>21</maven.compiler.source>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   </properties>
 </project>

examples/Benchmark/pom.xml

@@ -9,8 +9,8 @@
     <version>0.1.0</version>
 
     <properties>
-        <maven.compiler.source>17</maven.compiler.source>
-        <maven.compiler.target>17</maven.compiler.target>
+        <maven.compiler.source>21</maven.compiler.source>
+        <maven.compiler.target>21</maven.compiler.target>
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <jmh.version>1.37</jmh.version>
         <uberjar.name>benchmarks</uberjar.name>
@@ -32,12 +32,12 @@
         <dependency>
             <groupId>com.github.andrestubbe</groupId>
             <artifactId>FastCore</artifactId>
-            <version>main-SNAPSHOT</version>
+            <version>0.1.0</version>
         </dependency>
         <dependency>
             <groupId>com.github.andrestubbe</groupId>
             <artifactId>FastOverlay</artifactId>
-            <version>main-SNAPSHOT</version>
+            <version>0.1.0</version>
         </dependency>
         <dependency>
             <groupId>org.openjdk.jmh</groupId>

examples/Benchmark/src/main/java/fastghostmouse/benchmark/Benchmark.java

@@ -3,6 +3,9 @@
 import fastghostmouse.FastGhostMouse;
 import org.openjdk.jmh.annotations.*;
 
+import java.awt.Color;
+import java.awt.Graphics2D;
+import java.awt.image.BufferedImage;
 import java.util.concurrent.TimeUnit;
 
 @BenchmarkMode(Mode.Throughput)
@@ -14,20 +17,51 @@
 public class Benchmark {
 
     private FastGhostMouse ghostMouse;
+    private BufferedImage cursorImg;
+    private float moveTarget = 100.0f;
 
-    @Setup
+    @Setup(Level.Trial)
     public void setup() {
-        try {
-            ghostMouse = new FastGhostMouse();
-        } catch (Throwable t) {
-            ghostMouse = null;
+        ghostMouse = new FastGhostMouse();
+        ghostMouse.init(100, 100);
+
+        cursorImg = new BufferedImage(32, 32, BufferedImage.TYPE_INT_ARGB);
+        Graphics2D g = cursorImg.createGraphics();
+        g.setColor(new Color(255, 0, 0, 200));
+        g.fillOval(0, 0, 32, 32);
+        g.dispose();
+    }
+
+    @TearDown(Level.Trial)
+    public void tearDown() {
+        if (ghostMouse != null) {
+            ghostMouse.dispose();
         }
     }
 
+    @org.openjdk.jmh.annotations.Benchmark
+    public void benchmarkMoveToTarget() {
+        moveTarget = (moveTarget > 800.0f) ? 100.0f : moveTarget + 2.0f;
+        ghostMouse.moveTo(moveTarget, moveTarget);
+    }
+
+    @org.openjdk.jmh.annotations.Benchmark
+    public void benchmarkSetCursorPositionImmediate() {
+        ghostMouse.setCursorPositionImmediate(250, 250);
+    }
+
     @org.openjdk.jmh.annotations.Benchmark
     public void benchmarkSetTextOffset() {
-        if (ghostMouse != null) {
-            ghostMouse.setTextOffset(15.0f, -25.0f);
-        }
+        ghostMouse.setTextOffset(15.0f, -25.0f);
+    }
+
+    @org.openjdk.jmh.annotations.Benchmark
+    public void benchmarkSetSmoothing() {
+        ghostMouse.setSmoothing(0.18f);
+    }
+
+    @org.openjdk.jmh.annotations.Benchmark
+    public void benchmarkUpdateCursorImage() {
+        ghostMouse.setCursorImage(cursorImg);
     }
 }

run-benchmark.bat

@@ -1,30 +1,27 @@
 @echo off
-setlocal
-chcp 65001 > nul
+setlocal enabledelayedexpansion
+chcp 65001 >nul
 cd /d "%~dp0"
-set "MAVEN_OPTS=--enable-native-access=ALL-UNNAMED --sun-misc-unsafe-memory-access=allow -Dorg.slf4j.simpleLogger.defaultLogLevel=warn"
 
-echo ===================================================
-echo  Building FastGhostMouse ^& JMH Benchmarks Uber-Jar
-echo ===================================================
+echo ================================================================================
+echo   FastGhostMouse - Official JMH Performance Benchmark
+echo ================================================================================
+echo.
 
-call mvn -q clean install -DskipTests 2>nul
-if %ERRORLEVEL% NEQ 0 (
-    echo [ERROR] FastGhostMouse install failed!
-    pause
-    exit /b %ERRORLEVEL%
-)
+echo [1/3] Building Main Project (FastGhostMouse)...
+call mvn clean install -DskipTests -q
+if %ERRORLEVEL% NEQ 0 ( echo [ERROR] Main build failed. & pause & exit /b %ERRORLEVEL% )
 
+powershell -NoProfile -Command "Unblock-File -Path '%USERPROFILE%\.fastcore\native\fastghostmouse\*', '%~dp0build\*', '%~dp0src\main\resources\*' -ErrorAction SilentlyContinue" >nul 2>&1
+
+echo [2/3] Building Benchmark Uber-JAR...
 cd examples\Benchmark
-call mvn -q clean package 2>nul
-if %ERRORLEVEL% NEQ 0 (
-    echo [ERROR] Benchmark packaging failed!
-    pause
-    exit /b %ERRORLEVEL%
-)
+call mvn clean package -DskipTests -q
+if %ERRORLEVEL% NEQ 0 ( echo [ERROR] Benchmark build failed. & cd ..\.. & pause & exit /b %ERRORLEVEL% )
+
+echo [3/3] Running Official JMH Benchmarks for FastGhostMouse...
+java --enable-native-access=ALL-UNNAMED --sun-misc-unsafe-memory-access=allow -Djmh.ignoreLock=true "-Djava.library.path=..\..\src\main\resources\native;..\..\target\classes\native" -jar target\benchmarks.jar -f 1 -wi 2 -i 3 -tu ms -bm thrpt
 
-echo ===================================================
-echo  Running JMH Benchmarks (Throughput: ops/ms)
-echo ===================================================
-java --enable-native-access=ALL-UNNAMED --sun-misc-unsafe-memory-access=allow "-Djava.library.path=..\..\src\main\resources\native;..\..\target\classes\native;src\main\resources\native" -jar target\benchmarks.jar -f 1 -wi 2 -i 3 -tu ms -bm thrpt
+cd ..\..
+echo.
 pause

run-demo.bat

@@ -0,0 +1,21 @@
+@echo off
+setlocal
+cd /d "%~dp0"
+
+echo [1/3] Building FastGhostMouse...
+call mvn clean install -DskipTests -q
+if %ERRORLEVEL% NEQ 0 ( echo [ERROR] FastGhostMouse build failed. & pause & exit /b %ERRORLEVEL% )
+
+powershell -NoProfile -Command "Unblock-File -Path '%USERPROFILE%\.fastcore\native\fastghostmouse\*', '%~dp0build\*', '%~dp0src\main\resources\*' -ErrorAction SilentlyContinue" >nul 2>&1
+
+echo [2/3] Compiling Demo...
+cd examples\Demo
+call mvn compile dependency:build-classpath "-Dmdep.outputFile=cp.txt" "-DincludeScope=runtime" -q
+if %ERRORLEVEL% NEQ 0 ( echo [ERROR] Demo build failed. & cd ..\.. & pause & exit /b %ERRORLEVEL% )
+
+echo [3/3] Running FastGhostMouse Demo...
+set /p CP=<cp.txt
+java --enable-native-access=ALL-UNNAMED --sun-misc-unsafe-memory-access=allow "-Djava.library.path=%~dp0build;%~dp0src\main\resources\native" -cp "target\classes;%CP%" fastghostmouse.demo.Demo
+
+cd ..\..
+pause