cleonos/docs/stage30.md

# Stage 30 - User-Space Window Manager (UWM) + Mouse Syscall

## Goal
- Add a minimal user-space desktop environment entrypoint.
- Provide a usable user-space window manager (`uwm`) with focus, dragging, resize, taskbar, and launcher.
- Expose mouse snapshot data to user-space through a dedicated syscall.

## Implementation
- New syscall:
  - Added `MOUSE_STATE` (`id=107`) in kernel/user syscall headers.
  - Kernel side (`clks/kernel/runtime/syscall.c`) now exports mouse snapshot:
    - fields: `x`, `y`, `buttons`, `packet_count`, `ready`.
  - User wrapper added: `cleonos_sys_mouse_state()`.
- Window protocol update:
  - Added `WM_SET_FLAGS` (`id=114`) for `CLEONOS_WM_FLAG_TOPMOST`.
  - Added `WM_RESIZE` (`id=115`) so resize keeps the same `window_id`.
- New user app:
  - Added `cleonos/c/apps/uwm_main.c`.
  - Features:
    - Bottom taskbar with window buttons.
    - Start launcher menu for built-in demo windows.
    - Multiple windows with z-order.
    - Title bar with close, minimize, topmost, and resize controls.
    - Active window focus + border highlight.
    - Drag by title bar (left mouse).
    - Keyboard fallback controls (`Tab`, `1/2/3`, `W/A/S/D`, `M`, `X`, `T`, `+/-`, `Q`).
- Build integration:
  - Added `uwm` into shell command app set in `cleonos/CMakeLists.txt`.
  - Updated shell help text and standalone `help` app output.
- QEMU run/debug update:
  - QEMU now keeps the default PS/2 mouse path enabled for `make run`/`make debug`.
  - USB tablet is optional and disabled by default because the kernel currently has a PS/2 mouse driver, not a USB HID tablet driver.
  - Optional absolute pointer device:
    - `-usb -device usb-tablet`
  - New CMake option:
    - `CLEONOS_QEMU_ENABLE_USB_TABLET=OFF` (default).
    - Set it to `ON` only after USB HID tablet support is available.

## Acceptance Criteria
- `uwm` can be started from user shell.
- UWM draws multiple windows, taskbar, and launcher, and supports dragging, minimize/restore, topmost, close, and resize.
- Mouse state is retrievable from user-space via syscall `107`.
- `make run`/`make debug` use the PS/2 mouse path by default so the existing kernel mouse driver receives movement and buttons.

## Build Targets
- `make userapps`
- `make iso`
- `make run`

## QEMU Command
- `make run`

## Debug Notes
- If `uwm` reports framebuffer unavailable:
  - verify `FB_INFO` syscall is enabled and framebuffer bpp is `32`.
- If the UWM cursor does not move under QEMU:
  - keep `CLEONOS_QEMU_ENABLE_USB_TABLET=OFF`.
  - for manual QEMU invocation, do not include `-usb -device usb-tablet` until USB HID support exists.
- If mouse syscall returns `ready=0`:
  - check boot log for PS/2 mouse init status under `[INFO][MOUSE]`.