node-mac-recorder 2.24.15 → 2.24.17

package/src/ios_device_recorder.mm

@@ -17,7 +17,7 @@ extern "C" bool isStandaloneAudioRecording(void);
 extern "C" bool pauseIOSDeviceRecording(void);
 extern "C" bool resumeIOSDeviceRecording(void);
 
-@interface MRIOSDeviceRecorder : NSObject <AVCaptureFileOutputRecordingDelegate>
+@interface MRIOSDeviceRecorder : NSObject <AVCaptureFileOutputRecordingDelegate, AVCaptureFileOutputDelegate>
 @property(nonatomic, strong) AVCaptureSession *session;
 @property(nonatomic, strong) AVCaptureDeviceInput *deviceInput;
 @property(nonatomic, strong) AVCaptureMovieFileOutput *movieOutput;
@@ -27,6 +27,7 @@ extern "C" bool resumeIOSDeviceRecording(void);
 @property(atomic) BOOL finishCompleted;
 @property(atomic) BOOL startRequested;
 @property(atomic) BOOL stopRequested;
+@property(atomic) BOOL segmentStartPending;
 @property(atomic, strong) NSError *finishError;
 @property(atomic) BOOL paused;
 @property(atomic) BOOL segmentStartCompleted;
@@ -42,7 +43,8 @@ extern "C" bool resumeIOSDeviceRecording(void);
 @property(nonatomic) BOOL captureMicrophone;
 @property(nonatomic, copy) NSString *cameraOutputPath;
 @property(nonatomic, copy) NSString *audioOutputPath;
-@property(nonatomic, strong) NSDate *primaryStartedAt;
+@property(atomic) CMTime primaryStartHostTime;
+@property(atomic) CMTime stopHostTime;
 @end
 
 static BOOL MRIOSHasProducedMedia(MRIOSDeviceRecorder *recorder) {
@@ -67,10 +69,6 @@ static void MRIOSMarkSegmentStarted(MRIOSDeviceRecorder *recorder,
     recorder.segmentStartCompleted = YES;
     if (!recorder.startCompleted) {
         recorder.startCompleted = YES;
-        recorder.primaryStartedAt = [NSDate date];
-        if (!recorder.stopRequested) {
-            MRSyncMarkPrimaryStarted(CMClockGetTime(CMClockGetHostTimeClock()));
-        }
     }
     if (!confirmedByDelegate) {
         MRLog(@"✅ iPhone capture start confirmed from recorded media progress");
@@ -79,6 +77,36 @@ static void MRIOSMarkSegmentStarted(MRIOSDeviceRecorder *recorder,
 
 @implementation MRIOSDeviceRecorder
 
+- (BOOL)captureOutputShouldProvideSampleAccurateRecordingStart:(AVCaptureOutput *)output {
+    return YES;
+}
+
+- (void)captureOutput:(AVCaptureFileOutput *)output
+        didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
+        fromConnection:(AVCaptureConnection *)connection {
+    if (!self.segmentStartPending || !CMSampleBufferDataIsReady(sampleBuffer)) return;
+    @synchronized (self) {
+        if (!self.segmentStartPending || self.stopRequested) return;
+        CMTime hostTime = MRSyncHostTimestamp(
+            CMSampleBufferGetPresentationTimeStamp(sampleBuffer), self.session.masterClock);
+        if (!CMTIME_IS_NUMERIC(hostTime)) return;
+        self.segmentStartPending = NO;
+        @try {
+            // macOS guarantees that a start requested inside this delegate
+            // includes this exact sample. The later didStart/progress signal
+            // confirms success but must never redefine the media's origin.
+            [output startRecordingToOutputFileURL:[NSURL fileURLWithPath:self.currentSegmentPath]
+                               recordingDelegate:self];
+            self.primaryStartHostTime = hostTime;
+            MRSyncMarkPrimaryStarted(hostTime);
+        } @catch (NSException *exception) {
+            self.segmentFinishError = [NSError errorWithDomain:@"MacRecorderIOS" code:18
+                userInfo:@{NSLocalizedDescriptionKey: exception.reason ?: @"iPhone sample start failed"}];
+            self.segmentFinishCompleted = YES;
+        }
+    }
+}
+
 - (void)captureOutput:(AVCaptureFileOutput *)captureOutput
         didStartRecordingToOutputFileAtURL:(NSURL *)fileURL
         fromConnections:(NSArray<AVCaptureConnection *> *)connections {
@@ -303,27 +331,27 @@ static BOOL MRIOSFileOutputSucceeded(NSError *error) {
     return [successfullyFinished boolValue];
 }
 
-static NSTimeInterval MRIOSRecordedDurationSeconds(MRIOSDeviceRecorder *recorder) {
+static NSTimeInterval MRIOSRecordedDurationSeconds(MRIOSDeviceRecorder *recorder, CMTime hostTime) {
+    if (CMTIME_IS_NUMERIC(recorder.primaryStartHostTime)) {
+        return MAX(0.0, CMTimeGetSeconds(CMTimeSubtract(hostTime, recorder.primaryStartHostTime)));
+    }
     CMTime duration = recorder.movieOutput.recordedDuration;
     if (CMTIME_IS_NUMERIC(duration) &&
         CMTIME_COMPARE_INLINE(duration, >=, kCMTimeZero)) {
         return MAX(0.0, CMTimeGetSeconds(duration));
     }
-    if (recorder.primaryStartedAt) {
-        return MAX(0.0, -[recorder.primaryStartedAt timeIntervalSinceNow]);
-    }
     return 0.0;
 }
 
-static void MRIOSBeginPauseRange(MRIOSDeviceRecorder *recorder) {
-    recorder.pauseStartedAtSeconds = MRIOSRecordedDurationSeconds(recorder);
+static void MRIOSBeginPauseRange(MRIOSDeviceRecorder *recorder, CMTime hostTime) {
+    recorder.pauseStartedAtSeconds = MRIOSRecordedDurationSeconds(recorder, hostTime);
     MRLog(@"⏸️ iPhone capture pause marker at %.3f seconds",
           recorder.pauseStartedAtSeconds);
 }
 
-static void MRIOSEndPauseRange(MRIOSDeviceRecorder *recorder) {
+static void MRIOSEndPauseRange(MRIOSDeviceRecorder *recorder, CMTime hostTime) {
     if (recorder.pauseStartedAtSeconds < 0.0) return;
-    NSTimeInterval end = MRIOSRecordedDurationSeconds(recorder);
+    NSTimeInterval end = MRIOSRecordedDurationSeconds(recorder, hostTime);
     NSTimeInterval start = recorder.pauseStartedAtSeconds;
     recorder.pauseStartedAtSeconds = -1.0;
     if (end <= start) return;
@@ -358,8 +386,7 @@ static BOOL MRIOSStartNextSegment(MRIOSDeviceRecorder *recorder, NSError **error
     recorder.segmentFinishError = nil;
     recorder.recording = NO;
 
-    [recorder.movieOutput startRecordingToOutputFileURL:[NSURL fileURLWithPath:segmentPath]
-                                      recordingDelegate:recorder];
+    recorder.segmentStartPending = YES;
     // AVCaptureMovieFileOutput can begin writing before its delegate callback
     // is delivered. That callback may be queued behind Electron's synchronous
     // native call, so requiring only the callback creates a false timeout even
@@ -391,7 +418,7 @@ static BOOL MRIOSStartNextSegment(MRIOSDeviceRecorder *recorder, NSError **error
               (unsigned long)recorder.movieOutput.connections.count);
         if (errorOut) {
             BOOL connectedButNoFrames = recorder.session.isRunning &&
-                recorder.movieOutput.isRecording && durationSeconds <= 0.0;
+                (recorder.segmentStartPending || recorder.movieOutput.isRecording) && durationSeconds <= 0.0;
             *errorOut = recorder.segmentFinishError ?: (connectedButNoFrames
                 ? MRIOSNoFramesError()
                 : [NSError errorWithDomain:@"MacRecorderIOS"
@@ -405,9 +432,10 @@ static BOOL MRIOSStartNextSegment(MRIOSDeviceRecorder *recorder, NSError **error
 }
 
 static BOOL MRIOSStopCurrentSegment(MRIOSDeviceRecorder *recorder) {
-    if (recorder.movieOutput.isRecording) {
-        [recorder.movieOutput stopRecording];
+    @synchronized (recorder) {
+        recorder.segmentStartPending = NO;
     }
+    if (recorder.movieOutput.isRecording) [recorder.movieOutput stopRecording];
     if (recorder.segmentStartCompleted && !recorder.segmentFinishCompleted) {
         if (!MRWaitForFlag(^bool{ return recorder.segmentFinishCompleted; }, 20.0)) {
             MRLog(@"⚠️ iPhone segment is still finalizing");
@@ -692,7 +720,9 @@ extern "C" bool startIOSDeviceRecording(NSString *outputPath,
         recorder.captureMicrophone = captureMicrophone;
         recorder.cameraOutputPath = cameraOutputPath;
         recorder.audioOutputPath = audioOutputPath;
-        recorder.primaryStartedAt = nil;
+        recorder.primaryStartHostTime = kCMTimeInvalid;
+        recorder.stopHostTime = kCMTimeInvalid;
+        recorder.movieOutput.delegate = recorder;
 
         g_iosRecorder = recorder;
         [recorder.session beginConfiguration];
@@ -728,12 +758,11 @@ extern "C" bool startIOSDeviceRecording(NSString *outputPath,
         recorder.movieOutput.movieFragmentInterval = CMTimeMakeWithSeconds(2.0, 600);
         g_iosRecorder = recorder;
 
-        // Camera and microphone sessions are prepared first but discard their
-        // warm-up samples until AVCaptureMovieFileOutput confirms the iPhone's
-        // first frame. Every produced file therefore starts at the same t=0.
+        // Use the sample-accurate USB origin for every file, including a camera
+        // or microphone whose first callback arrives later.
         MRSyncConfigure(captureMicrophone);
         MRSyncConfigureCamera(captureCamera);
-        MRSyncConfigurePrimaryStart(captureCamera || captureMicrophone);
+        MRSyncConfigurePrimaryStart(YES);
 
         if (captureCamera) {
             NSError *cameraError = nil;
@@ -838,15 +867,24 @@ extern "C" bool stopIOSDeviceRecording(void) {
         MRIOSDeviceRecorder *recorder = g_iosRecorder;
         if (!recorder) return true;
 
-        recorder.stopRequested = YES;
-        if (recorder.primaryStartedAt) {
-            NSTimeInterval duration = MAX(0.0,
-                -[recorder.primaryStartedAt timeIntervalSinceNow] - MRSyncGetPausedDurationSeconds());
-            MRSyncSetStopLimitSeconds(duration);
+        CMTime stopHostTime;
+        @synchronized (recorder) {
+            if (!CMTIME_IS_NUMERIC(recorder.stopHostTime)) {
+                recorder.stopHostTime = CMClockGetTime(CMClockGetHostTimeClock());
+            }
+            stopHostTime = recorder.stopHostTime;
+            recorder.stopRequested = YES;
+            recorder.segmentStartPending = NO;
         }
+        // Request the USB stop before waiting for either auxiliary writer.
+        // Do not hold the delegate lock across an AVFoundation stop call.
+        if (recorder.movieOutput.isRecording) [recorder.movieOutput stopRecording];
         if (recorder.paused) {
-            MRIOSEndPauseRange(recorder);
+            MRIOSEndPauseRange(recorder, stopHostTime);
+            MRSyncResumeAtHostTime(stopHostTime);
         }
+        CMTime mediaStopTime = MRSyncPrimaryMediaTime(stopHostTime);
+        if (CMTIME_IS_NUMERIC(mediaStopTime)) MRSyncSetStopLimitSeconds(CMTimeGetSeconds(mediaStopTime));
 
         BOOL cameraStopped = YES;
         BOOL microphoneStopped = YES;
@@ -894,6 +932,7 @@ extern "C" bool stopIOSDeviceRecording(void) {
         } @catch (NSException *exception) {
             MRLog(@"⚠️ iPhone capture teardown warning: %@", exception.reason);
         }
+        recorder.movieOutput.delegate = nil;
         recorder.movieOutput = nil;
         recorder.deviceInput = nil;
         recorder.session = nil;
@@ -906,7 +945,7 @@ extern "C" bool stopIOSDeviceRecording(void) {
         recorder.outputPath = nil;
         recorder.cameraOutputPath = nil;
         recorder.audioOutputPath = nil;
-        recorder.primaryStartedAt = nil;
+        recorder.primaryStartHostTime = kCMTimeInvalid;
         g_iosRecorder = nil;
         [recorder release];
 
@@ -948,12 +987,13 @@ extern "C" bool pauseIOSDeviceRecording(void) {
             // Do not stop or pause AVCaptureMovieFileOutput here. USB iPhone
             // muxed sources may fail to re-arm their compressor on resume.
             // Capture continuously and trim this time range during finalization.
-            MRIOSBeginPauseRange(recorder);
-            MRSyncPause();
+            CMTime pauseHostTime = CMClockGetTime(CMClockGetHostTimeClock());
+            MRIOSBeginPauseRange(recorder, pauseHostTime);
+            MRSyncPauseAtHostTime(pauseHostTime);
             recorder.paused = YES;
             return true;
         } @catch (NSException *exception) {
-            MRSyncResume();
+            MRSyncResumeAtHostTime(CMClockGetTime(CMClockGetHostTimeClock()));
             MRLog(@"❌ iPhone pause failed: %@", exception.reason);
             return false;
         }
@@ -967,9 +1007,10 @@ extern "C" bool resumeIOSDeviceRecording(void) {
         if (!recorder.paused) return recorder.movieOutput.isRecording;
         if (!recorder.movieOutput.isRecording) return false;
         @try {
-            MRIOSEndPauseRange(recorder);
+            CMTime resumeHostTime = CMClockGetTime(CMClockGetHostTimeClock());
+            MRIOSEndPauseRange(recorder, resumeHostTime);
             recorder.paused = NO;
-            MRSyncResume();
+            MRSyncResumeAtHostTime(resumeHostTime);
             return true;
         } @catch (NSException *exception) {
             MRLog(@"❌ iPhone resume failed: %@", exception.reason);

package/src/sync_timeline.h

@@ -40,6 +40,16 @@ void MRSyncConfigurePrimaryStart(BOOL expectPrimary);
 void MRSyncMarkPrimaryStarted(CMTime timestamp);
 BOOL MRSyncShouldHoldForPrimary(CMTime timestamp);
 
+// iPhone-only timeline. Convert each capture session's PTS to the host clock
+// before comparing sources; preserve late arrivals instead of rebasing each
+// file to its own first sample. Invalid media time means discard the sample.
+BOOL MRSyncUsesPrimaryTimeline(void);
+CMTime MRSyncPrimaryStartTimestamp(void);
+CMTime MRSyncHostTimestamp(CMTime timestamp, CMClockRef captureClock);
+CMTime MRSyncPrimaryMediaTime(CMTime hostTimestamp);
+void MRSyncPauseAtHostTime(CMTime timestamp);
+void MRSyncResumeAtHostTime(CMTime timestamp);
+
 // Optional hard stop limit (seconds) shared across capture components.
 void MRSyncSetStopLimitSeconds(double seconds);
 double MRSyncGetStopLimitSeconds(void);

package/src/sync_timeline.mm

@@ -1,5 +1,6 @@
 #import "sync_timeline.h"
 #import "logging.h"
+#include <vector>
 
 static dispatch_queue_t MRSyncQueue() {
     static dispatch_once_t onceToken;
@@ -34,6 +35,8 @@ static BOOL g_primaryReady = YES;
 static CMTime g_primaryStartTimestamp = kCMTimeInvalid;
 static CMTime g_primaryHoldFirstTimestamp = kCMTimeInvalid;
 static BOOL g_primaryHoldLogged = NO;
+struct MRPrimaryPauseRange { CMTime start; CMTime end; };
+static std::vector<MRPrimaryPauseRange> g_primaryPauses;
 
 void MRSyncConfigure(BOOL expectAudio) {
     dispatch_sync(MRSyncQueue(), ^{
@@ -58,6 +61,7 @@ void MRSyncConfigure(BOOL expectAudio) {
         g_primaryStartTimestamp = kCMTimeInvalid;
         g_primaryHoldFirstTimestamp = kCMTimeInvalid;
         g_primaryHoldLogged = NO;
+        g_primaryPauses.clear();
     });
 }
 
@@ -94,7 +98,10 @@ double MRSyncGetPausedDurationSeconds(void) {
     __block double duration = 0;
     dispatch_sync(MRSyncQueue(), ^{
         duration = g_totalPausedSeconds;
-        if (g_isPaused && g_pauseStartedAt > 0) {
+        if (g_expectPrimary && g_isPaused && !g_primaryPauses.empty()) {
+            duration += MAX(0, CMTimeGetSeconds(CMTimeSubtract(
+                CMClockGetTime(CMClockGetHostTimeClock()), g_primaryPauses.back().start)));
+        } else if (g_isPaused && g_pauseStartedAt > 0) {
             duration += MAX(0, CFAbsoluteTimeGetCurrent() - g_pauseStartedAt);
         }
     });
@@ -318,12 +325,67 @@ void MRSyncConfigurePrimaryStart(BOOL expectPrimary) {
         g_primaryStartTimestamp = kCMTimeInvalid;
         g_primaryHoldFirstTimestamp = kCMTimeInvalid;
         g_primaryHoldLogged = NO;
+        g_primaryPauses.clear();
     });
     if (expectPrimary) {
         MRLog(@"🔄 A/V SYNC: Primary-source start barrier enabled");
     }
 }
 
+BOOL MRSyncUsesPrimaryTimeline(void) {
+    __block BOOL enabled = NO;
+    dispatch_sync(MRSyncQueue(), ^{ enabled = g_expectPrimary; });
+    return enabled;
+}
+
+CMTime MRSyncPrimaryStartTimestamp(void) {
+    __block CMTime timestamp = kCMTimeInvalid;
+    dispatch_sync(MRSyncQueue(), ^{ timestamp = g_primaryStartTimestamp; });
+    return timestamp;
+}
+
+CMTime MRSyncHostTimestamp(CMTime timestamp, CMClockRef captureClock) {
+    if (!CMTIME_IS_NUMERIC(timestamp) || !captureClock) return kCMTimeInvalid;
+    return CMSyncConvertTime(timestamp, captureClock, CMClockGetHostTimeClock());
+}
+
+CMTime MRSyncPrimaryMediaTime(CMTime hostTimestamp) {
+    if (!CMTIME_IS_NUMERIC(hostTimestamp)) return kCMTimeInvalid;
+    __block CMTime result = kCMTimeInvalid;
+    dispatch_sync(MRSyncQueue(), ^{
+        if (!g_expectPrimary || !CMTIME_IS_NUMERIC(g_primaryStartTimestamp) ||
+            CMTimeCompare(hostTimestamp, g_primaryStartTimestamp) < 0) return;
+        CMTime paused = kCMTimeZero;
+        for (const auto &range : g_primaryPauses) {
+            if (CMTimeCompare(hostTimestamp, range.start) < 0) break;
+            if (!CMTIME_IS_NUMERIC(range.end) || CMTimeCompare(hostTimestamp, range.end) < 0) return;
+            paused = CMTimeAdd(paused, CMTimeSubtract(range.end, range.start));
+        }
+        result = CMTimeSubtract(CMTimeSubtract(hostTimestamp, g_primaryStartTimestamp), paused);
+    });
+    return result;
+}
+
+void MRSyncPauseAtHostTime(CMTime timestamp) {
+    if (!CMTIME_IS_NUMERIC(timestamp)) return;
+    dispatch_sync(MRSyncQueue(), ^{
+        if (!g_expectPrimary || g_isPaused) return;
+        g_primaryPauses.push_back({timestamp, kCMTimeInvalid});
+        g_isPaused = YES;
+    });
+}
+
+void MRSyncResumeAtHostTime(CMTime timestamp) {
+    if (!CMTIME_IS_NUMERIC(timestamp)) return;
+    dispatch_sync(MRSyncQueue(), ^{
+        if (!g_expectPrimary || !g_isPaused || g_primaryPauses.empty()) return;
+        auto &range = g_primaryPauses.back();
+        range.end = CMTimeMaximum(timestamp, range.start);
+        g_totalPausedSeconds += CMTimeGetSeconds(CMTimeSubtract(range.end, range.start));
+        g_isPaused = NO;
+    });
+}
+
 void MRSyncMarkPrimaryStarted(CMTime timestamp) {
     if (!CMTIME_IS_VALID(timestamp)) return;
 

package/tests/cursor-detection-probe.mm

@@ -0,0 +1,207 @@
+// Exercise the production detector with real AppKit images, including detached
+// bitmap copies as returned for cursors belonging to other applications.
+#import "../src/cursor_tracker.mm"
+
+static Napi::Value RunCursorTests(const Napi::CallbackInfo &info) {
+    @autoreleasepool {
+        NSMutableArray<NSString *> *failures = [NSMutableArray array];
+        NSUInteger checks = 0;
+        auto expect = [&](NSString *actual, NSString *expected, NSString *label) {
+            checks++;
+            if (!StringsEqual(actual, expected)) {
+                [failures addObject:[NSString stringWithFormat:@"%@: expected %@, got %@", label, expected, actual]];
+            }
+        };
+        InitializeCursorFingerprintMap();
+        auto checkCursor = [&](NSCursor *cursor, NSString *expected, NSString *label) {
+            expect(normalizeCursorTypeForDesktop(cursorTypeFromNSCursor(cursor)), expected, label);
+            NSImage *image = cursor.image;
+            if (!image || image.size.width <= 0 || image.size.height <= 0) {
+                [failures addObject:[label stringByAppendingString:@": AppKit image unavailable"]];
+                return;
+            }
+            for (NSUInteger scale = 1; scale <= 2; scale++) {
+                NSSize size = image.size;
+                NSBitmapImageRep *bitmap = [[[NSBitmapImageRep alloc]
+                    initWithBitmapDataPlanes:NULL pixelsWide:lround(size.width * scale)
+                    pixelsHigh:lround(size.height * scale) bitsPerSample:8 samplesPerPixel:4
+                    hasAlpha:YES isPlanar:NO colorSpaceName:NSDeviceRGBColorSpace
+                    bytesPerRow:0 bitsPerPixel:0] autorelease];
+                bitmap.size = size;
+                [NSGraphicsContext saveGraphicsState];
+                [NSGraphicsContext setCurrentContext:[NSGraphicsContext graphicsContextWithBitmapImageRep:bitmap]];
+                [image drawInRect:NSMakeRect(0, 0, size.width, size.height) fromRect:NSZeroRect
+                    operation:NSCompositingOperationCopy fraction:1.0];
+                [NSGraphicsContext restoreGraphicsState];
+                NSImage *copy = [[[NSImage alloc] initWithSize:size] autorelease];
+                [copy addRepresentation:bitmap];
+                NSCursor *detached = [[[NSCursor alloc] initWithImage:copy hotSpot:cursor.hotSpot] autorelease];
+                expect(normalizeCursorTypeForDesktop(cursorTypeFromNSCursor(detached)), expected,
+                    [NSString stringWithFormat:@"%@ detached %lux", label, (unsigned long)scale]);
+            }
+        };
+
+        NSDictionary *names = @{
+            @"contextualMenuCursor": @"default", @"dragLinkCursor": @"alias",
+            @"move": @"all-scroll", @"help": @"help", @"zoomOutCursor": @"zoom-out",
+            @"n-resize": @"ns-resize", @"s-resize": @"ns-resize",
+            @"e-resize": @"col-resize", @"w-resize": @"col-resize",
+            @"ne-resize": @"nesw-resize", @"sw-resize": @"nesw-resize",
+            @"nw-resize": @"nwse-resize", @"se-resize": @"nwse-resize",
+            @"resizeNorthEastCursor": @"nesw-resize", @"resizeNorthWestCursor": @"nwse-resize",
+            @"row-resize": @"row-resize", @"col-resize": @"col-resize",
+            @"resizeNorthSouthCursor": @"ns-resize", @"resizeEastWestCursor": @"col-resize"
+        };
+        for (NSString *name in names) {
+            expect(normalizeCursorTypeForDesktop(cursorTypeFromCursorName(name)), names[name], name);
+        }
+        expect(cursorTypeFromCursorName(@"unknown-resize"), nil, @"unknown direction must remain unknown");
+
+        checkCursor(NSCursor.arrowCursor, @"default", @"arrow");
+        checkCursor(NSCursor.pointingHandCursor, @"pointer", @"pointing hand");
+        checkCursor(NSCursor.IBeamCursor, @"text", @"text");
+        checkCursor(NSCursor.crosshairCursor, @"crosshair", @"crosshair");
+        checkCursor(NSCursor.openHandCursor, @"grab", @"open hand");
+        checkCursor(NSCursor.closedHandCursor, @"grabbing", @"closed hand");
+        checkCursor(NSCursor.dragCopyCursor, @"copy", @"copy");
+        checkCursor(NSCursor.dragLinkCursor, @"alias", @"alias");
+        checkCursor(NSCursor.operationNotAllowedCursor, @"not-allowed", @"not allowed");
+        if ([NSCursor instancesRespondToSelector:NSSelectorFromString(@"_coreCursorType")]) {
+            checkCursor([[[MRSystemReferenceCursor alloc] initWithCoreType:39] autorelease], @"all-scroll", @"CoreCursor move");
+            checkCursor([[[MRSystemReferenceCursor alloc] initWithCoreType:11] autorelease], @"grabbing", @"CoreCursor closed hand");
+            checkCursor([[[MRSystemReferenceCursor alloc] initWithCoreType:12] autorelease], @"grab", @"CoreCursor open hand");
+        }
+        if (@available(macOS 15.0, *)) {
+            checkCursor(NSCursor.zoomInCursor, @"zoom-in", @"zoom in");
+            checkCursor(NSCursor.zoomOutCursor, @"zoom-out", @"zoom out");
+            for (NSUInteger direction = 1; direction <= 3; direction++) {
+                checkCursor([NSCursor rowResizeCursorInDirections:(NSVerticalDirections)direction], @"row-resize", @"row");
+                checkCursor([NSCursor columnResizeCursorInDirections:(NSHorizontalDirections)direction], @"col-resize", @"column");
+                const NSCursorFrameResizePosition positions[] = {
+                    NSCursorFrameResizePositionTop, NSCursorFrameResizePositionBottom,
+                    NSCursorFrameResizePositionLeft, NSCursorFrameResizePositionRight,
+                    NSCursorFrameResizePositionTopLeft, NSCursorFrameResizePositionBottomRight,
+                    NSCursorFrameResizePositionTopRight, NSCursorFrameResizePositionBottomLeft
+                };
+                NSArray *expected = @[@"ns-resize", @"ns-resize", @"col-resize", @"col-resize",
+                    @"nwse-resize", @"nwse-resize", @"nesw-resize", @"nesw-resize"];
+                for (NSUInteger i = 0; i < 8; i++) {
+                    checkCursor([NSCursor frameResizeCursorFromPosition:positions[i]
+                        inDirections:(NSCursorFrameResizeDirections)direction], expected[i],
+                        [NSString stringWithFormat:@"frame %lu direction %lu", (unsigned long)i, (unsigned long)direction]);
+                }
+            }
+        }
+
+        NSDictionary *resources = @{
+            @"help": @"help", @"busybutclickable": @"progress", @"move": @"all-scroll",
+            @"zoomin": @"zoom-in", @"zoomout": @"zoom-out",
+            @"resizenortheast": @"nesw-resize", @"resizesouthwest": @"nesw-resize",
+            @"resizenorthwest": @"nwse-resize", @"resizesoutheast": @"nwse-resize",
+            @"resizenortheastsouthwest": @"nesw-resize", @"resizenorthwestsoutheast": @"nwse-resize",
+            @"resizenorthsouth": @"ns-resize", @"resizeupdown": @"row-resize"
+        };
+        NSString *resourceRoot = @"/System/Library/Frameworks/ApplicationServices.framework/Versions/A/Frameworks/HIServices.framework/Versions/A/Resources/cursors";
+        for (NSString *resource in resources) {
+            NSString *directory = [resourceRoot stringByAppendingPathComponent:resource];
+            NSImage *image = [[[NSImage alloc] initWithContentsOfFile:[directory stringByAppendingPathComponent:@"cursor.pdf"]] autorelease];
+            if (!image) continue; // Legacy resources are optional on future macOS versions.
+            NSDictionary *metadata = [NSDictionary dictionaryWithContentsOfFile:[directory stringByAppendingPathComponent:@"info.plist"]];
+            NSCursor *cursor = [[[NSCursor alloc] initWithImage:image
+                hotSpot:NSMakePoint([metadata[@"hotx"] doubleValue], [metadata[@"hoty"] doubleValue])] autorelease];
+            checkCursor(cursor, resources[resource], resource);
+        }
+
+        // Unrelated custom cursors may have exactly the old heuristic dimensions.
+        NSImage *custom = [[[NSImage alloc] initWithSize:NSMakeSize(22, 22)] autorelease];
+        [custom lockFocus];
+        [[NSColor redColor] setFill];
+        NSRectFill(NSMakeRect(0, 0, 22, 22));
+        [custom unlockFocus];
+        NSCursor *customCursor = [[[NSCursor alloc] initWithImage:custom hotSpot:NSMakePoint(11, 11)] autorelease];
+        expect(cursorTypeFromNSCursor(customCursor), @"default", @"unknown 22x22 custom image");
+
+        ResetCursorEventHistory();
+        RememberCursorEvent(CGPointMake(100, 100), @"default", @"move");
+        expect(ShouldEmitCursorEvent(CGPointMake(100, 100), @"nesw-resize", @"move") ? @"yes" : @"no", @"yes", @"stationary shape change");
+        expect(ShouldEmitCursorEvent(CGPointMake(100, 100), @"default", @"move") ? @"yes" : @"no", @"no", @"stationary duplicate");
+        RememberCursorEvent(CGPointMake(100, 100), @"nwse-resize", @"drag");
+        expect(ShouldEmitCursorEvent(CGPointMake(100, 100), @"nesw-resize", @"drag") ? @"yes" : @"no", @"yes", @"stationary drag shape change");
+        ResetCursorEventHistory();
+
+        Napi::Object result = Napi::Object::New(info.Env());
+        result.Set("checks", Napi::Number::New(info.Env(), checks));
+        result.Set("failures", Napi::String::New(info.Env(), [[failures componentsJoinedByString:@"\n"] UTF8String]));
+        return result;
+    }
+}
+
+// Opt-in integration test: briefly display owned cursors and read them back from
+// WindowServer. Restore the previous system cursor even when an assertion fails.
+static Napi::Value RunLiveCursorTests(const Napi::CallbackInfo &info) {
+    @autoreleasepool {
+        [NSApplication sharedApplication];
+        InitializeCursorFingerprintMap();
+        NSMutableArray *failures = [NSMutableArray array];
+        NSMutableArray<NSCursor *> *cursors = [NSMutableArray arrayWithObjects:NSCursor.arrowCursor,
+            NSCursor.IBeamCursor, NSCursor.pointingHandCursor, NSCursor.openHandCursor,
+            NSCursor.closedHandCursor, NSCursor.dragCopyCursor, NSCursor.dragLinkCursor,
+            NSCursor.operationNotAllowedCursor, NSCursor.crosshairCursor, nil];
+        NSMutableArray *types = [NSMutableArray arrayWithArray:@[@"default", @"text", @"pointer",
+            @"grab", @"grabbing", @"copy", @"alias", @"not-allowed", @"crosshair"]];
+        if ([NSCursor instancesRespondToSelector:NSSelectorFromString(@"_coreCursorType")]) {
+            [cursors addObject:[[[MRSystemReferenceCursor alloc] initWithCoreType:39] autorelease]];
+            [types addObject:@"all-scroll"];
+        }
+        if (@available(macOS 15.0, *)) {
+            [cursors addObjectsFromArray:@[NSCursor.zoomInCursor, NSCursor.zoomOutCursor,
+                NSCursor.columnResizeCursor, NSCursor.rowResizeCursor,
+                [NSCursor frameResizeCursorFromPosition:NSCursorFrameResizePositionTop inDirections:NSCursorFrameResizeDirectionsAll],
+                [NSCursor frameResizeCursorFromPosition:NSCursorFrameResizePositionTopLeft inDirections:NSCursorFrameResizeDirectionsAll],
+                [NSCursor frameResizeCursorFromPosition:NSCursorFrameResizePositionTopRight inDirections:NSCursorFrameResizeDirectionsAll]]];
+            [types addObjectsFromArray:@[@"zoom-in", @"zoom-out", @"col-resize", @"row-resize", @"ns-resize", @"nwse-resize", @"nesw-resize"]];
+        }
+        NSCursor *previous = [[NSCursor currentSystemCursor] retain];
+        NSRunningApplication *previousApp = [[NSWorkspace sharedWorkspace].frontmostApplication retain];
+        NSPoint mouse = NSEvent.mouseLocation;
+        [NSApp setActivationPolicy:NSApplicationActivationPolicyAccessory];
+        NSWindow *window = [[NSWindow alloc] initWithContentRect:NSMakeRect(mouse.x - 80, mouse.y - 60, 160, 120)
+            styleMask:NSWindowStyleMaskTitled backing:NSBackingStoreBuffered defer:NO];
+        window.releasedWhenClosed = NO;
+        window.title = @"Cursor detection test";
+        [window disableCursorRects];
+        @try {
+            [window makeKeyAndOrderFront:nil];
+            [NSApp activateIgnoringOtherApps:YES];
+            [[NSRunLoop currentRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.2]];
+            for (NSUInteger i = 0; i < cursors.count; i++) {
+                [cursors[i] set];
+                [[NSRunLoop currentRunLoop] runUntilDate:[NSDate dateWithTimeIntervalSinceNow:0.03]];
+                NSString *actual = getCursorType();
+                if (!StringsEqual(actual, types[i])) {
+                    NSCursor *system = NSCursor.currentSystemCursor;
+                    [failures addObject:[NSString stringWithFormat:@"%@: got %@ (system image %@, hotspot %@)",
+                        types[i], actual, NSStringFromSize(system.image.size), NSStringFromPoint(system.hotSpot)]];
+                }
+            }
+        } @finally {
+            [window close];
+            [window release];
+            [previousApp activateWithOptions:NSApplicationActivateIgnoringOtherApps];
+            [previousApp release];
+            [previous set];
+            [previous release];
+        }
+        Napi::Object result = Napi::Object::New(info.Env());
+        result.Set("checks", Napi::Number::New(info.Env(), cursors.count));
+        result.Set("failures", Napi::String::New(info.Env(), [[failures componentsJoinedByString:@"\n"] UTF8String]));
+        return result;
+    }
+}
+
+static Napi::Object InitProbe(Napi::Env env, Napi::Object exports) {
+    exports.Set("run", Napi::Function::New(env, RunCursorTests));
+    exports.Set("runLive", Napi::Function::New(env, RunLiveCursorTests));
+    return exports;
+}
+NODE_API_MODULE(cursor_detection_probe, InitProbe)

package/tests/cursor-detection.test.cjs

@@ -0,0 +1,37 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+test('native system cursor detection preserves resize axes, shapes and stationary changes', {
+  skip: process.platform !== 'darwin', timeout: 120000,
+}, (t) => {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'recorder-cursor-test-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  const version = process.versions.node;
+  const candidates = [
+    process.env.npm_config_nodedir && path.join(process.env.npm_config_nodedir, 'include/node'),
+    path.join(os.homedir(), 'Library/Caches/node-gyp', version, 'include/node'),
+    path.join(os.homedir(), '.cache/node-gyp', version, 'include/node'),
+    path.resolve(path.dirname(process.execPath), '../include/node'),
+  ].filter(Boolean);
+  const headers = candidates.find((p) => fs.existsSync(path.join(p, 'node_api.h')));
+  assert.ok(headers, 'Node headers required; run npm run rebuild first');
+  const binary = path.join(directory, 'cursor-probe.node');
+  execFileSync('xcrun', ['clang++', '-std=c++17', '-bundle', '-undefined', 'dynamic_lookup',
+    '-DNAPI_DISABLE_CPP_EXCEPTIONS', '-Wno-deprecated-declarations',
+    '-I', headers, '-I', path.dirname(require.resolve('node-addon-api')),
+    path.join(__dirname, 'cursor-detection-probe.mm'), '-o', binary,
+    '-framework', 'AppKit', '-framework', 'ApplicationServices', '-framework', 'Carbon',
+  ], { timeout: 60000, stdio: 'pipe' });
+  const result = require(binary).run();
+  t.diagnostic(`${result.checks} native cursor checks`);
+  assert.equal(result.failures, '');
+  if (process.env.MAC_RECORDER_TEST_LIVE_CURSOR === '1') {
+    const live = require(binary).runLive();
+    t.diagnostic(`${live.checks} WindowServer cursor checks`);
+    assert.equal(live.failures, '');
+  }
+});

package/tests/cursor-electron.test.cjs

@@ -0,0 +1,26 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+test('Chromium move and hand cursors survive native capture and press/release', {
+  skip: process.platform !== 'darwin', timeout: 20000,
+}, (t) => {
+  let electron = process.env.MAC_RECORDER_ELECTRON;
+  if (!electron) {
+    try { electron = require('electron'); } catch {}
+  }
+  assert.equal(typeof electron, 'string', 'Set MAC_RECORDER_ELECTRON to the Electron executable');
+  const env = { ...process.env };
+  delete env.ELECTRON_RUN_AS_NODE;
+  const run = spawnSync(electron, [path.join(__dirname, 'electron-cursor-fixture.cjs')], {
+    env, encoding: 'utf8', timeout: 18000,
+  });
+  assert.ifError(run.error);
+  const output = run.stdout.split('\n').find(line => line.startsWith('CURSOR_RESULTS='));
+  assert.ok(output, run.stderr || 'Electron did not return cursor samples');
+  const results = JSON.parse(output.slice('CURSOR_RESULTS='.length));
+  assert.deepEqual(results.filter(({ expected, actual }) => expected !== actual), []);
+  assert.equal(run.status, 0, run.stderr);
+  t.diagnostic(`${results.length} real Electron CSS cursor checks`);
+});