node-mac-recorder 1.14.0 → 1.14.2

package/CLAUDE.md

@@ -73,10 +73,22 @@ The package handles complex multi-display coordinate transformations:
 - `checkPermissions()` - Verify macOS recording permissions
 
 ### Cursor Tracking
-- `startCursorCapture(filepath)` - Begin real-time cursor tracking to JSON
+- `startCursorCapture(filepath, options)` - Begin real-time cursor tracking to JSON
+  - `options.windowInfo` - Window information for window-relative coordinates
+  - `options.windowRelative` - Set to true for window-relative coordinates
 - `stopCursorCapture()` - Stop tracking and close output file
 - `getCursorPosition()` - Get current cursor position and state
 
+### Events
+The MacRecorder class emits the following events:
+- `recordingStarted` - Emitted immediately when recording starts with recording details
+- `started` - Emitted when recording is confirmed started (legacy event)
+- `stopped` - Emitted when recording stops
+- `completed` - Emitted when recording file is finalized
+- `timeUpdate` - Emitted every second with elapsed time
+- `cursorCaptureStarted` - Emitted when cursor capture begins
+- `cursorCaptureStopped` - Emitted when cursor capture ends
+
 ### Thumbnails
 - `getWindowThumbnail(windowId, options)` - Capture window preview image
 - `getDisplayThumbnail(displayId, options)` - Capture display preview image
@@ -90,9 +102,14 @@ The package handles complex multi-display coordinate transformations:
 
 ### Common Development Patterns
 - All recording operations are Promise-based
-- Event emission for recording state changes (`started`, `stopped`, `completed`)
+- Event emission for recording state changes (`recordingStarted`, `started`, `stopped`, `completed`)
+- `recordingStarted` event provides immediate notification with recording details
 - Automatic permission checking before operations
 - Error handling with descriptive messages for permission issues
+- Cursor tracking supports multiple coordinate systems:
+  - Global coordinates (default)
+  - Display-relative coordinates (when recording)
+  - Window-relative coordinates (with windowInfo parameter)
 
 ### Platform Requirements
 - macOS only (enforced in install.js)
@@ -102,6 +119,13 @@ The package handles complex multi-display coordinate transformations:
 ### File Outputs
 - Video recordings: `.mov` format (H.264/AAC)
 - Cursor data: JSON format with timestamped events
+  - `x`, `y`: Cursor coordinates (coordinate system dependent)
+  - `timestamp`: Time from capture start (ms)
+  - `unixTimeMs`: Unix timestamp
+  - `cursorType`: macOS cursor type
+  - `type`: Event type (move, click, etc.)
+  - `coordinateSystem`: "global", "display-relative", or "window-relative"
+  - `windowInfo`: Window metadata (when using window-relative coordinates)
 - Thumbnails: Base64-encoded PNG data URIs
 
 ## Troubleshooting

package/index.js

@@ -302,6 +302,13 @@ class MacRecorder extends EventEmitter {
 						this.emit("timeUpdate", elapsed);
 					}, 1000);
 
+					// Kayıt tam başladığı anda event emit et
+					this.emit("recordingStarted", {
+						outputPath: this.outputPath,
+						timestamp: this.recordingStartTime,
+						options: this.options
+					});
+					
 					this.emit("started", this.outputPath);
 					resolve(this.outputPath);
 				} else {
@@ -506,9 +513,12 @@ class MacRecorder extends EventEmitter {
 	/**
 	 * Cursor capture başlatır - otomatik olarak dosyaya yazmaya başlar
 	 * Recording başlatılmışsa otomatik olarak display-relative koordinatlar kullanır
-	 * @param {string} filepath - Cursor data JSON dosya yolu
+	 * @param {string|number} intervalOrFilepath - Cursor data JSON dosya yolu veya interval
+	 * @param {Object} options - Cursor capture seçenekleri
+	 * @param {Object} options.windowInfo - Pencere bilgileri (window-relative koordinatlar için)
+	 * @param {boolean} options.windowRelative - Koordinatları pencereye göre relative yap
 	 */
-	async startCursorCapture(intervalOrFilepath = 100) {
+	async startCursorCapture(intervalOrFilepath = 100, options = {}) {
 		let filepath;
 		let interval = 20; // Default 50 FPS
 
@@ -528,8 +538,20 @@ class MacRecorder extends EventEmitter {
 			throw new Error("Cursor capture is already running");
 		}
 
-		// Recording başlatılmışsa o display'i kullan, yoksa main display kullan
-		if (this.recordingDisplayInfo) {
+		// Koordinat sistemi belirle: window-relative, display-relative veya global
+		if (options.windowRelative && options.windowInfo) {
+			// Window-relative koordinatlar için pencere bilgilerini kullan
+			this.cursorDisplayInfo = {
+				displayId: options.windowInfo.displayId || null,
+				x: options.windowInfo.x || 0,
+				y: options.windowInfo.y || 0,
+				width: options.windowInfo.width,
+				height: options.windowInfo.height,
+				windowRelative: true,
+				windowInfo: options.windowInfo
+			};
+		} else if (this.recordingDisplayInfo) {
+			// Recording başlatılmışsa o display'i kullan
 			this.cursorDisplayInfo = this.recordingDisplayInfo;
 		} else {
 			// Main display bilgisini al (her zaman relative koordinatlar için)
@@ -568,23 +590,42 @@ class MacRecorder extends EventEmitter {
 						const position = nativeBinding.getCursorPosition();
 						const timestamp = Date.now() - this.cursorCaptureStartTime;
 
-						// Global koordinatları display-relative'e çevir
+						// Global koordinatları relative koordinatlara çevir
 						let x = position.x;
 						let y = position.y;
+						let coordinateSystem = "global";
 
 						if (this.cursorDisplayInfo) {
-							// Display offset'lerini çıkar
+							// Offset'leri çıkar (display veya window)
 							x = position.x - this.cursorDisplayInfo.x;
 							y = position.y - this.cursorDisplayInfo.y;
 
-							// Display bounds kontrolü - cursor display dışındaysa kaydetme
-							if (
-								x < 0 ||
-								y < 0 ||
-								x >= this.cursorDisplayInfo.width ||
-								y >= this.cursorDisplayInfo.height
-							) {
-								return; // Bu frame'i skip et
+							if (this.cursorDisplayInfo.windowRelative) {
+								// Window-relative koordinatlar
+								coordinateSystem = "window-relative";
+								
+								// Window bounds kontrolü - cursor window dışındaysa kaydetme
+								if (
+									x < 0 ||
+									y < 0 ||
+									x >= this.cursorDisplayInfo.width ||
+									y >= this.cursorDisplayInfo.height
+								) {
+									return; // Bu frame'i skip et - cursor pencere dışında
+								}
+							} else {
+								// Display-relative koordinatlar
+								coordinateSystem = "display-relative";
+								
+								// Display bounds kontrolü
+								if (
+									x < 0 ||
+									y < 0 ||
+									x >= this.cursorDisplayInfo.width ||
+									y >= this.cursorDisplayInfo.height
+								) {
+									return; // Bu frame'i skip et - cursor display dışında
+								}
 							}
 						}
 
@@ -595,6 +636,14 @@ class MacRecorder extends EventEmitter {
 							unixTimeMs: Date.now(),
 							cursorType: position.cursorType,
 							type: position.eventType || "move",
+							coordinateSystem: coordinateSystem,
+							...(this.cursorDisplayInfo?.windowRelative && {
+								windowInfo: {
+									width: this.cursorDisplayInfo.width,
+									height: this.cursorDisplayInfo.height,
+									originalWindow: this.cursorDisplayInfo.windowInfo
+								}
+							})
 						};
 
 						// Sadece eventType değiştiğinde veya pozisyon değiştiğinde kaydet

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "node-mac-recorder",
-	"version": "1.14.0",
+	"version": "1.14.2",
 	"description": "Native macOS screen recording package for Node.js applications",
 	"main": "index.js",
 	"keywords": [

package/src/window_selector.mm

@@ -16,6 +16,7 @@ static NSDictionary *g_selectedWindowInfo = nil;
 static NSMutableArray *g_allWindows = nil;
 static NSDictionary *g_currentWindowUnderCursor = nil;
 static bool g_bringToFrontEnabled = true; // Default enabled
+static id g_windowKeyEventMonitor = nil;
 
 // Recording preview overlay state
 static NSWindow *g_recordingPreviewWindow = nil;
@@ -213,6 +214,7 @@ bool hideScreenRecordingPreview();
 @interface WindowSelectorDelegate : NSObject
 - (void)selectButtonClicked:(id)sender;
 - (void)screenSelectButtonClicked:(id)sender;
+- (void)cancelButtonClicked:(id)sender;
 - (void)timerUpdate:(NSTimer *)timer;
 @end
 
@@ -241,6 +243,16 @@ bool hideScreenRecordingPreview();
     }
 }
 
+- (void)cancelButtonClicked:(id)sender {
+    NSLog(@"🚫 CANCEL BUTTON CLICKED: Selection cancelled");
+    // Clean up without selecting anything
+    if (g_isScreenSelecting) {
+        cleanupScreenSelector();
+    } else {
+        cleanupWindowSelector();
+    }
+}
+
 - (void)timerUpdate:(NSTimer *)timer {
     updateOverlay();
 }
@@ -495,14 +507,33 @@ void updateOverlay() {
             [(WindowSelectorOverlayView *)g_overlayView setWindowInfo:windowUnderCursor];
             [g_overlayView setNeedsDisplay:YES];
             
-            // Position select button in center
+            // Position buttons - Start Record in center, Cancel below it
             if (g_selectButton) {
                 NSSize buttonSize = [g_selectButton frame].size;
                 NSPoint buttonCenter = NSMakePoint(
                     (width - buttonSize.width) / 2,
-                    (height - buttonSize.height) / 2
+                    (height - buttonSize.height) / 2 + 30  // Slightly above center
                 );
                 [g_selectButton setFrameOrigin:buttonCenter];
+                
+                // Position cancel button below the main button
+                NSButton *cancelButton = nil;
+                for (NSView *subview in [g_overlayWindow.contentView subviews]) {
+                    if ([subview isKindOfClass:[NSButton class]] && 
+                        [[(NSButton*)subview title] isEqualToString:@"Cancel"]) {
+                        cancelButton = (NSButton*)subview;
+                        break;
+                    }
+                }
+                
+                if (cancelButton) {
+                    NSSize cancelButtonSize = [cancelButton frame].size;
+                    NSPoint cancelButtonCenter = NSMakePoint(
+                        (width - cancelButtonSize.width) / 2,
+                        buttonCenter.y - buttonSize.height - 20  // 20px below main button
+                    );
+                    [cancelButton setFrameOrigin:cancelButtonCenter];
+                }
             }
             
             [g_overlayWindow orderFront:nil];
@@ -535,6 +566,12 @@ void cleanupWindowSelector() {
         g_trackingTimer = nil;
     }
     
+    // Remove key event monitor
+    if (g_windowKeyEventMonitor) {
+        [NSEvent removeMonitor:g_windowKeyEventMonitor];
+        g_windowKeyEventMonitor = nil;
+    }
+    
     // Close overlay window
     if (g_overlayWindow) {
         [g_overlayWindow close];
@@ -752,14 +789,52 @@ bool startScreenSelection() {
             [selectButton setTarget:g_delegate];
             [selectButton setAction:@selector(screenSelectButtonClicked:)];
             
-            // Position button in center of screen
+            // Create cancel button for screen selection
+            NSButton *screenCancelButton = [[NSButton alloc] initWithFrame:NSMakeRect(0, 0, 120, 40)];
+            [screenCancelButton setTitle:@"Cancel"];
+            [screenCancelButton setButtonType:NSButtonTypeMomentaryPushIn];
+            [screenCancelButton setBezelStyle:NSBezelStyleRounded];
+            [screenCancelButton setFont:[NSFont systemFontOfSize:14 weight:NSFontWeightMedium]];
+            
+            // Gray cancel button styling
+            [screenCancelButton setWantsLayer:YES];
+            [screenCancelButton.layer setBackgroundColor:[[NSColor colorWithRed:0.5 green:0.5 blue:0.5 alpha:0.8] CGColor]];
+            [screenCancelButton.layer setCornerRadius:6.0];
+            [screenCancelButton.layer setBorderColor:[[NSColor colorWithRed:0.4 green:0.4 blue:0.4 alpha:1.0] CGColor]];
+            [screenCancelButton.layer setBorderWidth:1.0];
+            
+            // White text for cancel button
+            NSMutableAttributedString *screenCancelTitleString = [[NSMutableAttributedString alloc] 
+                initWithString:[screenCancelButton title]];
+            [screenCancelTitleString addAttribute:NSForegroundColorAttributeName 
+                                value:[NSColor whiteColor] 
+                                range:NSMakeRange(0, [screenCancelTitleString length])];
+            [screenCancelButton setAttributedTitle:screenCancelTitleString];
+            
+            // Add shadow for cancel button
+            [screenCancelButton.layer setShadowColor:[[NSColor blackColor] CGColor]];
+            [screenCancelButton.layer setShadowOffset:NSMakeSize(0, -1)];
+            [screenCancelButton.layer setShadowRadius:2.0];
+            [screenCancelButton.layer setShadowOpacity:0.2];
+            
+            [screenCancelButton setTarget:g_delegate];
+            [screenCancelButton setAction:@selector(cancelButtonClicked:)];
+            
+            // Position buttons - Start Record in center, Cancel below it
             NSPoint buttonCenter = NSMakePoint(
                 (screenFrame.size.width - [selectButton frame].size.width) / 2,
-                (screenFrame.size.height - [selectButton frame].size.height) / 2
+                (screenFrame.size.height - [selectButton frame].size.height) / 2 + 30  // Slightly above center
             );
             [selectButton setFrameOrigin:buttonCenter];
             
+            NSPoint cancelButtonCenter = NSMakePoint(
+                (screenFrame.size.width - [screenCancelButton frame].size.width) / 2,
+                buttonCenter.y - [selectButton frame].size.height - 20  // 20px below main button
+            );
+            [screenCancelButton setFrameOrigin:cancelButtonCenter];
+            
             [overlayView addSubview:selectButton];
+            [overlayView addSubview:screenCancelButton];
             [overlayWindow orderFront:nil];
             [overlayWindow makeKeyAndOrderFront:nil];
             
@@ -946,13 +1021,59 @@ Napi::Value StartWindowSelection(const Napi::CallbackInfo& info) {
         [g_selectButton setTarget:g_delegate];
         [g_selectButton setAction:@selector(selectButtonClicked:)];
         
-        [g_overlayView addSubview:g_selectButton];
+        // Add select button directly to window (not view) for proper layering
+        [g_overlayWindow.contentView addSubview:g_selectButton];
+        
+        // Create cancel button
+        NSButton *cancelButton = [[NSButton alloc] initWithFrame:NSMakeRect(0, 0, 120, 40)];
+        [cancelButton setTitle:@"Cancel"];
+        [cancelButton setButtonType:NSButtonTypeMomentaryPushIn];
+        [cancelButton setBezelStyle:NSBezelStyleRounded];
+        [cancelButton setFont:[NSFont systemFontOfSize:14 weight:NSFontWeightMedium]];
+        
+        // Gray cancel button styling
+        [cancelButton setWantsLayer:YES];
+        [cancelButton.layer setBackgroundColor:[[NSColor colorWithRed:0.5 green:0.5 blue:0.5 alpha:0.8] CGColor]];
+        [cancelButton.layer setCornerRadius:6.0];
+        [cancelButton.layer setBorderColor:[[NSColor colorWithRed:0.4 green:0.4 blue:0.4 alpha:1.0] CGColor]];
+        [cancelButton.layer setBorderWidth:1.0];
+        
+        // White text for cancel button
+        NSMutableAttributedString *cancelTitleString = [[NSMutableAttributedString alloc] 
+            initWithString:[cancelButton title]];
+        [cancelTitleString addAttribute:NSForegroundColorAttributeName 
+                            value:[NSColor whiteColor] 
+                            range:NSMakeRange(0, [cancelTitleString length])];
+        [cancelButton setAttributedTitle:cancelTitleString];
+        
+        // Add shadow for cancel button
+        [cancelButton.layer setShadowColor:[[NSColor blackColor] CGColor]];
+        [cancelButton.layer setShadowOffset:NSMakeSize(0, -1)];
+        [cancelButton.layer setShadowRadius:2.0];
+        [cancelButton.layer setShadowOpacity:0.2];
+        
+        [cancelButton setTarget:g_delegate];
+        [cancelButton setAction:@selector(cancelButtonClicked:)];
+        
+        // Add cancel button to window
+        [g_overlayWindow.contentView addSubview:cancelButton];
+        
+        // Cancel button reference will be found dynamically in positioning code
         
         // Timer approach doesn't work well with Node.js
         // Instead, we'll use JavaScript polling via getWindowSelectionStatus
         // The JS side will call this function repeatedly to trigger overlay updates
         g_trackingTimer = nil; // No timer for now
         
+        // Add ESC key event monitor to cancel selection
+        g_windowKeyEventMonitor = [NSEvent addGlobalMonitorForEventsMatchingMask:NSEventMaskKeyDown
+                                                                      handler:^(NSEvent *event) {
+            if ([event keyCode] == 53) { // ESC key
+                NSLog(@"🪟 WINDOW SELECTION: ESC pressed - cancelling selection");
+                cleanupWindowSelector();
+            }
+        }];
+        
         g_isWindowSelecting = true;
         g_selectedWindowInfo = nil;