Add mouse cursor overlay to screenshots

- Create cursor-overlay.ts utility with SVG-based cursor generation
- Modify screendump() to capture cursor position and overlay cursor
- Cursor is rendered as black arrow with white outline for visibility
- Fallback to screenshot without cursor if overlay fails

This enables users to see the mouse position in screenshots sent to the API.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: DBOYttt

packages/bytebotd/src/nut/cursor-overlay.ts

@@ -0,0 +1,68 @@
+import * as sharp from 'sharp';
+
+/**
+ * Creates a cursor image as a Buffer.
+ * The cursor is a simple arrow pointer shape.
+ */
+export async function createCursorImage(
+  size: number = 24,
+  color: string = '#000000',
+  outlineColor: string = '#FFFFFF',
+): Promise<Buffer> {
+  // Create a simple arrow cursor SVG
+  const svg = `
+    <svg width="${size}" height="${size}" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+      <!-- White outline for visibility on dark backgrounds -->
+      <path d="M 2 2 L 2 20 L 7 15 L 12 22 L 15 20 L 10 13 L 17 13 Z"
+            fill="none"
+            stroke="${outlineColor}"
+            stroke-width="2"
+            stroke-linejoin="round"/>
+      <!-- Black fill -->
+      <path d="M 2 2 L 2 20 L 7 15 L 12 22 L 15 20 L 10 13 L 17 13 Z"
+            fill="${color}"/>
+    </svg>
+  `;
+
+  return sharp(Buffer.from(svg)).png().toBuffer();
+}
+
+/**
+ * Overlays a cursor image onto a screenshot at the specified position.
+ *
+ * @param screenshotBuffer The screenshot image buffer
+ * @param cursorX The x coordinate of the cursor
+ * @param cursorY The y coordinate of the cursor
+ * @param cursorSize The size of the cursor (default 24)
+ * @returns A Buffer containing the screenshot with cursor overlay
+ */
+export async function overlayeCursorOnScreenshot(
+  screenshotBuffer: Buffer,
+  cursorX: number,
+  cursorY: number,
+  cursorSize: number = 24,
+): Promise<Buffer> {
+  // Create the cursor image
+  const cursorBuffer = await createCursorImage(cursorSize);
+
+  // Get screenshot metadata to ensure cursor stays within bounds
+  const metadata = await sharp(screenshotBuffer).metadata();
+  const width = metadata.width || 1920;
+  const height = metadata.height || 1080;
+
+  // Ensure cursor position is within screenshot bounds
+  const safeX = Math.max(0, Math.min(cursorX, width - 1));
+  const safeY = Math.max(0, Math.min(cursorY, height - 1));
+
+  // Composite the cursor onto the screenshot
+  return sharp(screenshotBuffer)
+    .composite([
+      {
+        input: cursorBuffer,
+        left: Math.round(safeX),
+        top: Math.round(safeY),
+      },
+    ])
+    .png()
+    .toBuffer();
+}

packages/bytebotd/src/nut/nut.service.ts

@@ -11,6 +11,7 @@ import {
 } from '@nut-tree-fork/nut-js';
 import { spawn } from 'child_process';
 import * as path from 'path';
+import { overlayeCursorOnScreenshot } from './cursor-overlay';
 
 /**
  * Enum representing key codes supported by nut-js.
@@ -463,21 +464,59 @@ export class NutService {
   }
 
   /**
-   * Takes a screenshot of the screen.
+   * Takes a screenshot of the screen with cursor overlay.
    *
+   * @param includeCursor Whether to include the mouse cursor in the screenshot (default: true)
    * @returns A Promise that resolves with a Buffer containing the image.
    */
-  async screendump(): Promise<Buffer> {
+  async screendump(includeCursor: boolean = true): Promise<Buffer> {
     const filename = `screenshot-${Date.now()}.png`;
     const filepath = path.join(this.screenshotDir, filename);
     this.logger.log(`Taking screenshot to ${filepath}`);
 
     try {
+      // Get cursor position before taking screenshot
+      let cursorPosition: { x: number; y: number } | null = null;
+      if (includeCursor) {
+        try {
+          cursorPosition = await mouse.getPosition();
+          this.logger.log(
+            `Cursor position: (${cursorPosition.x}, ${cursorPosition.y})`,
+          );
+        } catch (cursorError) {
+          this.logger.warn(
+            `Failed to get cursor position: ${cursorError.message}`,
+          );
+        }
+      }
+
       // Take screenshot
       await screen.capture(filename, FileType.PNG, this.screenshotDir);
 
-      // Read the file back and return as buffer
-      return await import('fs').then((fs) => fs.promises.readFile(filepath));
+      // Read the file back
+      const screenshotBuffer = await import('fs').then((fs) =>
+        fs.promises.readFile(filepath),
+      );
+
+      // Overlay cursor if position was captured
+      if (includeCursor && cursorPosition) {
+        try {
+          const withCursor = await overlayeCursorOnScreenshot(
+            screenshotBuffer,
+            cursorPosition.x,
+            cursorPosition.y,
+          );
+          this.logger.log('Cursor overlay applied to screenshot');
+          return withCursor;
+        } catch (overlayError) {
+          this.logger.warn(
+            `Failed to overlay cursor: ${overlayError.message}. Returning screenshot without cursor.`,
+          );
+          return screenshotBuffer;
+        }
+      }
+
+      return screenshotBuffer;
     } catch (error) {
       this.logger.error(`Error taking screenshot: ${error.message}`);
       throw error;