Add reapply mode to eliminate cursor flash on Helper startup

- Refactor applyCape() to applyCapeInternal(dictionary, isReapply)
- Add applyCapeReapply() and applyCapeAtPathReapply() functions
- Update listen.m: all 3 call sites use reapply mode (startSessionMonitor, UserSpaceChanged, reconfigurationCallback)
- Add MCLibraryController applyCapeReapply: method
- AppState.swift: smart dispatch based on MCAppliedCursor comparison
- Update CLAUDE.md: document reapply mode architecture

Reapply mode skips resetAllCursors() + backupAllCursors() when re-applying
the same cape, eliminating the visible flash back to system default cursors.
CGSRegisterCursorWithImages() can directly overwrite registered cursors.

Fresh apply (with reset) is preserved for: switching capes, first-time
application, CLI mousecloak apply, and explicit reset to default.

(cherry picked from commit e45cf6fd7f204288bfecb52e6a5a743a009da351)

Author: sdmj76

Mousecape/Mousecape

@@ -18,6 +18,10 @@ extern BOOL applyCursorForIdentifier(NSUInteger frameCount, CGFloat frameDuratio
 extern BOOL applyCapeForIdentifier(NSDictionary *cursor, NSString *identifier, BOOL restore);
 extern BOOL applyCape(NSDictionary *dictionary);
 extern BOOL applyCapeAtPath(NSString *path);
+// Reapply mode: skip resetAllCursors() + backupAllCursors() to avoid cursor flash.
+// Use when re-applying the same cape (Helper startup, session change, display reconfiguration).
+extern BOOL applyCapeReapply(NSDictionary *dictionary);
+extern BOOL applyCapeAtPathReapply(NSString *path);
 
 NS_ASSUME_NONNULL_END
 

Mousecape/mousecloak/apply.h

@@ -268,14 +268,18 @@ BOOL applyCapeForIdentifier(NSDictionary *cursor, NSString *identifier, BOOL res
     return applyCursorForIdentifier(frameCount.unsignedIntegerValue, frameDuration.doubleValue, hotSpot, size, images, identifier, 0);
 }
 
-BOOL applyCape(NSDictionary *dictionary) {
+// Internal implementation with reapply mode support.
+// When isReapply is YES, skip resetAllCursors() + backupAllCursors() to avoid
+// the visible flash when re-applying the same cape (e.g. Helper startup, session change).
+// CGSRegisterCursorWithImages() can directly overwrite already-registered cursors.
+static BOOL applyCapeInternal(NSDictionary *dictionary, BOOL isReapply) {
     @autoreleasepool {
         NSDictionary *cursors = dictionary[MCCursorDictionaryCursorsKey];
         NSString *name = dictionary[MCCursorDictionaryCapeNameKey];
         NSNumber *version = dictionary[MCCursorDictionaryCapeVersionKey];
 
         MMLog("========================================");
-        MMLog("=== APPLYING CAPE ===");
+        MMLog("=== APPLYING CAPE (%s) ===", isReapply ? "REAPPLY" : "FRESH");
         MMLog("========================================");
         MMLog("Cape name: %s", name.UTF8String);
         MMLog("Cape identifier: %s", [dictionary[MCCursorDictionaryIdentifierKey] UTF8String]);
@@ -286,10 +290,14 @@ BOOL applyCape(NSDictionary *dictionary) {
             MMLog("  - %s", key.UTF8String);
         }
 
-        MMLog("--- Calling resetAllCursors ---");
-        resetAllCursors();
-        MMLog("--- Calling backupAllCursors ---");
-        backupAllCursors();
+        if (!isReapply) {
+            MMLog("--- Calling resetAllCursors ---");
+            resetAllCursors();
+            MMLog("--- Calling backupAllCursors ---");
+            backupAllCursors();
+        } else {
+            MMLog("--- Skipping reset/backup (reapply mode) ---");
+        }
 
         MMLog("--- Applying cursors ---");
 
@@ -344,6 +352,14 @@ BOOL applyCape(NSDictionary *dictionary) {
     }
 }
 
+BOOL applyCape(NSDictionary *dictionary) {
+    return applyCapeInternal(dictionary, NO);
+}
+
+BOOL applyCapeReapply(NSDictionary *dictionary) {
+    return applyCapeInternal(dictionary, YES);
+}
+
 BOOL applyCapeAtPath(NSString *path) {
     MMLog("========================================");
     MMLog("=== applyCapeAtPath ===");
@@ -386,3 +402,46 @@ BOOL applyCapeAtPath(NSString *path) {
     MMLog(BOLD RED "Could not parse valid cape file" RESET);
     return NO;
 }
+
+BOOL applyCapeAtPathReapply(NSString *path) {
+    MMLog("========================================");
+    MMLog("=== applyCapeAtPathReapply ===");
+    MMLog("========================================");
+    MMLog("Input path: %s", path ? path.UTF8String : "(null)");
+
+    // Validate path
+    if (!path || path.length == 0) {
+        MMLog(BOLD RED "Invalid path" RESET);
+        return NO;
+    }
+
+    // Resolve symlinks and check for path traversal
+    NSString *realPath = [path stringByResolvingSymlinksInPath];
+    NSString *standardPath = [realPath stringByStandardizingPath];
+
+    MMLog("Real path: %s", realPath.UTF8String);
+    MMLog("Standard path: %s", standardPath.UTF8String);
+    MMLog("File exists: %s", [[NSFileManager defaultManager] fileExistsAtPath:standardPath] ? "YES" : "NO");
+    MMLog("File readable: %s", [[NSFileManager defaultManager] isReadableFileAtPath:standardPath] ? "YES" : "NO");
+
+    // Validate file extension
+    if (![[standardPath pathExtension] isEqualToString:@"cape"]) {
+        MMLog(BOLD RED "Invalid file extension - must be .cape" RESET);
+        return NO;
+    }
+
+    // Check file exists and is readable
+    if (![[NSFileManager defaultManager] isReadableFileAtPath:standardPath]) {
+        MMLog(BOLD RED "File not readable at path" RESET);
+        return NO;
+    }
+
+    MMLog("Loading cape file...");
+    NSDictionary *cape = [NSDictionary dictionaryWithContentsOfFile:standardPath];
+    if (cape) {
+        MMLog("Cape file loaded successfully, applying in reapply mode...");
+        return applyCapeReapply(cape);
+    }
+    MMLog(BOLD RED "Could not parse valid cape file" RESET);
+    return NO;
+}

Mousecape/mousecloak/apply.m

@@ -76,7 +76,7 @@ static void UserSpaceChanged(SCDynamicStoreRef	store, CFArrayRef changedKeys, vo
 
     // Only attempt to apply if there's a valid cape path
     if (appliedPath) {
-        BOOL success = applyCapeAtPath(appliedPath);
+        BOOL success = applyCapeAtPathReapply(appliedPath);
         MMLog("Apply result: %s", success ? "SUCCESS" : "FAILED");
         if (!success) {
             MMLog(BOLD RED "Application of cape failed" RESET);
@@ -107,7 +107,7 @@ void reconfigurationCallback(CGDirectDisplayID display,
     NSString *capePath = appliedCapePathForUser(NSUserName());
     MMLog("Cape path: %s", capePath ? capePath.UTF8String : "(none)");
     if (capePath) {
-        BOOL success = applyCapeAtPath(capePath);
+        BOOL success = applyCapeAtPathReapply(capePath);
         MMLog("Apply result: %s", success ? "SUCCESS" : "FAILED");
     }
     float scale;
@@ -227,7 +227,7 @@ void startSessionMonitor(void) {
     // Apply the cape for the user on load (if configured)
     NSString *initialCapePath = appliedCapePathForUser(NSUserName());
     if (initialCapePath) {
-        BOOL applySuccess = applyCapeAtPath(initialCapePath);
+        BOOL applySuccess = applyCapeAtPathReapply(initialCapePath);
         MMLog("Initial apply result: %s", applySuccess ? "SUCCESS" : "FAILED");
     } else {
         MMLog("No cape configured - running in standby mode");