feat/toggle cursor visibility (#87)

# Checklist

- [X] A link to a related issue in our repository:
https://linear.app/onkernel/issue/KERNEL-443/api-expose-option-to-hide-remote-browser-cursor-in-api
- [x] A description of the changes proposed in the pull request.



<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> Introduces POST /computer/cursor to hide/show the cursor via
unclutter, updates OpenAPI and generated client/server code, adds
runtime dependency and docs for local testing.
> 
> - **API/Backend**:
> - **New endpoint** `POST /computer/cursor` with `SetCursorRequest {
hidden: boolean }` to hide/show the cursor.
> - Implements `SetCursor` in `server/cmd/api/api/computer.go` (kills
existing `unclutter`, optionally starts new with `DISPLAY`, idle=0,
large jitter).
> - Updates generated OAPI code: models, client methods, server
handlers, routing, and response parsers; embeds updated swagger.
> - **Images**:
> - Adds `unclutter` to runtime packages in
`images/chromium-headful/Dockerfile`.
>   - Minor build script: logs image index/name in `build-unikernel.sh`.
> - **Docs**:
> - Adds `images/README.md` with local testing steps and example curl
for the new endpoint.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
51ef3a0. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: mateoCuervo

images/README.md

@@ -0,0 +1,15 @@
+## How to test kernel-images changes locally with docker
+
+- Make relevant changes to kernel-images example adding a new endpoint at `kernel-images/server/cmd/api/api/computer.go`, example I added `SetCursor()` endpoint.
+- Run openApi to generate the boilerplate for the new endpoints with make oapi-generate
+- Check changes at `kernel-images/server/lib/oapi/oapi.go`
+- `cd kernel-images/images/chromium-headful`
+-  Build and run the docker image with `./build-docker.sh && ENABLE_WEBRTC=true ./run-docker.sh`
+- Open http://localhost:8080/ in your browser
+- Now new endpoint should be available for tests example curl command:
+```sh
+curl -X POST localhost:444/computer/cursor \
+  -H "Content-Type: application/json" \
+  -d '{"hidden": true}'
+```
+

images/chromium-headful/Dockerfile

@@ -223,7 +223,7 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked,id=$CACHEIDPREFIX-ap
     set -eux; \
     apt-get update; \
     apt-get --no-install-recommends -y install \
-    wget ca-certificates python2 supervisor xclip xdotool \
+    wget ca-certificates python2 supervisor xclip xdotool unclutter \
     pulseaudio dbus-x11 xserver-xorg-video-dummy \
     libcairo2 libxcb1 libxrandr2 libxv1 libopus0 libvpx7 \
     x11-xserver-utils \

images/chromium-headful/build-unikernel.sh

@@ -25,6 +25,8 @@ docker cp cnt-"$app_name":/ ./.rootfs
 rm -f initrd || true
 sudo mkfs.erofs --all-root -d2 -E noinline_data -b 4096 initrd ./.rootfs
 
+echo "Image index/name: $UKC_INDEX/$IMAGE"
+
 # Package the unikernel (and the new initrd) to KraftCloud
 kraft pkg \
   --name $UKC_INDEX/$IMAGE \

server/cmd/api/api/computer.go

@@ -9,6 +9,7 @@ import (
 	"os"
 	"os/exec"
 	"strconv"
+	"syscall"
 	"time"
 
 	"github.com/onkernel/kernel-images/server/lib/logger"
@@ -362,6 +363,71 @@ func (s *ApiService) TypeText(ctx context.Context, request oapi.TypeTextRequestO
 	return oapi.TypeText200Response{}, nil
 }
 
+const (
+
+	// Unclutter configuration for cursor hiding
+	// Setting idle to 0 hides the cursor immediately
+	unclutterIdleSeconds = "0"
+
+	// A very large jitter value (9 million pixels) ensures that all mouse
+	// movements are treated as "noise", keeping the cursor permanently hidden
+	// when combined with idle=0
+	unclutterJitterPixels = "9000000"
+)
+
+func (s *ApiService) SetCursor(ctx context.Context, request oapi.SetCursorRequestObject) (oapi.SetCursorResponseObject, error) {
+	log := logger.FromContext(ctx)
+
+	// serialize input operations to avoid overlapping commands
+	s.inputMu.Lock()
+	defer s.inputMu.Unlock()
+
+	// Validate request body
+	if request.Body == nil {
+		return oapi.SetCursor400JSONResponse{BadRequestErrorJSONResponse: oapi.BadRequestErrorJSONResponse{
+			Message: "request body is required"},
+		}, nil
+	}
+	body := *request.Body
+
+	// Kill any existing unclutter processes first
+	pkillCmd := exec.CommandContext(ctx, "pkill", "unclutter")
+	pkillCmd.SysProcAttr = &syscall.SysProcAttr{
+		Credential: &syscall.Credential{Uid: 0, Gid: 0},
+	}
+
+	if err := pkillCmd.Run(); err != nil {
+		if exitErr, ok := err.(*exec.ExitError); !ok || exitErr.ExitCode() != 1 {
+			log.Error("failed to kill existing unclutter processes", "err", err)
+			return oapi.SetCursor500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{
+				Message: "failed to kill existing unclutter processes"},
+			}, nil
+		}
+	}
+
+	if body.Hidden {
+		display := s.resolveDisplayFromEnv()
+		unclutterCmd := exec.CommandContext(context.Background(),
+			"unclutter",
+			"-idle", unclutterIdleSeconds,
+			"-jitter", unclutterJitterPixels,
+		)
+		unclutterCmd.Env = append(os.Environ(), fmt.Sprintf("DISPLAY=%s", display))
+		unclutterCmd.SysProcAttr = &syscall.SysProcAttr{
+			Credential: &syscall.Credential{Uid: 0, Gid: 0},
+		}
+
+		if err := unclutterCmd.Start(); err != nil {
+			log.Error("failed to start unclutter", "err", err)
+			return oapi.SetCursor500JSONResponse{InternalErrorJSONResponse: oapi.InternalErrorJSONResponse{
+				Message: "failed to start unclutter"},
+			}, nil
+		}
+	}
+
+	return oapi.SetCursor200JSONResponse{Ok: true}, nil
+}
+
 func (s *ApiService) PressKey(ctx context.Context, request oapi.PressKeyRequestObject) (oapi.PressKeyResponseObject, error) {
 	log := logger.FromContext(ctx)