From 778be3cd2c4441fd23c9450d0cd3020cbce66df8 Mon Sep 17 00:00:00 2001 From: SH20RAJ Date: Wed, 8 Oct 2025 13:09:52 +0530 Subject: [PATCH] feat: Add macOS Tahoe cursor and wallpaper support structure - Add Tahoe wallpaper entries to ConfigSidebar (tahoe-dark, tahoe-light) - Add comprehensive documentation for extracting Tahoe cursor hashes - Add code comments explaining Tahoe cursor support requirements - Create TAHOE_SUPPORT.md guide for adding cursor support - Create TAHOE_WALLPAPERS_NEEDED.md for wallpaper guidelines - Update cursor-info README with Tahoe compatibility notes This prepares the codebase for macOS Tahoe (macOS 16) support. Once Tahoe is publicly available or beta access is obtained: 1. Cursor hashes can be extracted using cursors.html 2. Tahoe wallpapers can be added to assets/backgrounds/macOS/ 3. Cursor SVGs can be updated if designs changed Related: #1100 --- .../macOS/TAHOE_WALLPAPERS_NEEDED.md | 81 +++++++ .../src/routes/editor/ConfigSidebar.tsx | 2 + crates/cursor-info/README.md | 15 ++ crates/cursor-info/TAHOE_SUPPORT.md | 204 ++++++++++++++++++ crates/cursor-info/src/macos.rs | 26 +++ 5 files changed, 328 insertions(+) create mode 100644 apps/desktop/src-tauri/assets/backgrounds/macOS/TAHOE_WALLPAPERS_NEEDED.md create mode 100644 crates/cursor-info/TAHOE_SUPPORT.md diff --git a/apps/desktop/src-tauri/assets/backgrounds/macOS/TAHOE_WALLPAPERS_NEEDED.md b/apps/desktop/src-tauri/assets/backgrounds/macOS/TAHOE_WALLPAPERS_NEEDED.md new file mode 100644 index 0000000000..61e128c4fe --- /dev/null +++ b/apps/desktop/src-tauri/assets/backgrounds/macOS/TAHOE_WALLPAPERS_NEEDED.md @@ -0,0 +1,81 @@ +# macOS Tahoe Wallpapers Needed + +This document outlines the macOS Tahoe wallpapers that need to be added to complete issue #1100. + +## Required Wallpapers + +The following macOS Tahoe wallpapers should be added to this directory: + +1. **tahoe-dark.jpg** - Dark variant of macOS Tahoe default wallpaper +2. **tahoe-light.jpg** - Light variant of macOS Tahoe default wallpaper + +## Wallpaper Specifications + +- **Format**: JPEG (.jpg) +- **Recommended Resolution**: At least 3840x2160 (4K) or higher +- **Quality**: High quality, preferably from official macOS Tahoe beta/release +- **Style**: Should match the "Liquid Glass" design language introduced in macOS Tahoe + +## How to Obtain Wallpapers + +### For Users with macOS Tahoe Access: + +1. The wallpapers can be found in: + ``` + /System/Library/Desktop Pictures/ + ``` + +2. Or extract from system resources using: + ```bash + # Example command (exact location may vary) + find /System/Library -name "*Tahoe*" -o -name "*tahoe*" + ``` + +### Alternative Sources: + +- Download from Apple's official macOS Tahoe resources (when publicly available) +- Extract from macOS Tahoe Developer Beta (requires Apple Developer Program membership) +- Community-shared high-quality recreations matching the Tahoe aesthetic + +## Adding the Wallpapers + +Once you have the wallpaper files: + +1. Add `tahoe-dark.jpg` and `tahoe-light.jpg` to this directory +2. Ensure file names match exactly (lowercase) +3. Delete this `TAHOE_WALLPAPERS_NEEDED.md` file +4. Test that the wallpapers appear in the Cap editor's background selector + +## Integration Notes + +The wallpapers have already been added to the wallpaper selector in: +- `apps/desktop/src/routes/editor/ConfigSidebar.tsx` + +The entries are: +- `"macOS/tahoe-dark"` +- `"macOS/tahoe-light"` + +These entries will automatically work once the corresponding `.jpg` files are added to this directory. + +## Quality Guidelines + +- Images should be authentic macOS Tahoe wallpapers or high-quality recreations +- Resolution should be sufficient for modern displays (4K minimum recommended) +- Color accuracy is important to match the macOS Tahoe aesthetic +- Compression should be balanced (high quality but reasonable file size) + +## Testing + +After adding the wallpapers: + +1. Launch Cap in development mode +2. Open the editor +3. Navigate to the background selection +4. Verify that "Tahoe Dark" and "Tahoe Light" appear in the macOS section +5. Select each wallpaper and confirm it displays correctly +6. Test on both Retina and non-Retina displays if possible + +--- + +**Related Issue**: #1100 - Add support for macOS Tahoe Icons +**PR**: TBD diff --git a/apps/desktop/src/routes/editor/ConfigSidebar.tsx b/apps/desktop/src/routes/editor/ConfigSidebar.tsx index 3663d04e78..3ef1f1fa0a 100644 --- a/apps/desktop/src/routes/editor/ConfigSidebar.tsx +++ b/apps/desktop/src/routes/editor/ConfigSidebar.tsx @@ -137,6 +137,8 @@ const BACKGROUND_GRADIENTS = [ const WALLPAPER_NAMES = [ // macOS wallpapers + "macOS/tahoe-dark", + "macOS/tahoe-light", "macOS/sequoia-dark", "macOS/sequoia-light", "macOS/sonoma-clouds", diff --git a/crates/cursor-info/README.md b/crates/cursor-info/README.md index 3bef7782f6..91f6109cdd 100644 --- a/crates/cursor-info/README.md +++ b/crates/cursor-info/README.md @@ -156,6 +156,21 @@ macOS cursor detection uses SHA-256 hashing of the cursor's TIFF image data. Thi - Cursors are resolution-independent - Hash comparison provides reliable identification +#### macOS Version Compatibility + +The current implementation supports cursor detection for macOS versions up to Sequoia (macOS 15). + +**macOS Tahoe (macOS 16) Support:** +macOS Tahoe introduces a new "Liquid Glass" design language which may include updated cursor designs with different visual appearance. If cursor icons have changed in Tahoe, new cursor hashes will need to be extracted and added to the `from_hash()` function in `src/macos.rs`. + +To add Tahoe cursor support: +1. Run `cursors.html` on a macOS Tahoe system +2. Compare the generated hashes with existing ones +3. If hashes differ, extract the new cursor SVG assets +4. Update `src/macos.rs` with new hashes +5. Update assets in `assets/mac/` if cursor designs have changed +6. Test cursor detection on Tahoe to ensure proper identification + ### Windows Implementation Windows cursor detection uses `HCURSOR` handle comparison with a cached lookup table of system cursors loaded at runtime. diff --git a/crates/cursor-info/TAHOE_SUPPORT.md b/crates/cursor-info/TAHOE_SUPPORT.md new file mode 100644 index 0000000000..c2c9f9a649 --- /dev/null +++ b/crates/cursor-info/TAHOE_SUPPORT.md @@ -0,0 +1,204 @@ +# macOS Tahoe Cursor Support Guide + +## Overview + +This guide explains how to add support for macOS Tahoe (macOS 16) cursors to the Cap cursor-info crate. macOS Tahoe introduces a new "Liquid Glass" design language which may include updated cursor icon designs. + +## Current Status + +- ✅ Code structure prepared for Tahoe cursor support +- ✅ Documentation added for Tahoe cursor extraction process +- ✅ Wallpaper support added for macOS Tahoe backgrounds +- ⏳ Pending: Actual Tahoe cursor hashes (requires macOS Tahoe access) +- ⏳ Pending: Updated cursor SVG assets (if designs have changed) + +## Why Tahoe Support May Be Needed + +macOS Tahoe features a refreshed visual design system called "Liquid Glass" which includes: +- Updated app icons with refined appearance +- Transparent menu bars and controls +- Refined visual elements throughout the OS + +If Apple has updated the cursor designs to match this new aesthetic, the cursor image data will be different, resulting in new SHA-256 hashes. This means existing cursors may not be detected properly on macOS Tahoe. + +## How to Add Tahoe Cursor Support + +### Prerequisites + +- Access to a macOS Tahoe (macOS 16) system (beta or release) +- Basic familiarity with running Rust projects +- Understanding of SHA-256 hashing + +### Step 1: Extract Cursor Hashes + +1. On a macOS Tahoe system, open `crates/cursor-info/cursors.html` in a web browser + +2. The page will display all system cursors with their current hashes + +3. For each cursor type, note the hash value displayed + +4. Compare these hashes with the existing hashes in `src/macos.rs` (line ~138+) + +5. Document any hashes that differ from the current implementation + +### Step 2: Determine If Visual Changes Occurred + +1. If hashes are identical to existing ones: No changes needed! Tahoe uses the same cursor designs. + +2. If hashes differ: Cursor designs have changed and need to be extracted + +### Step 3: Extract Updated Cursor SVGs (If Needed) + +If cursor hashes have changed, you'll need to extract the new cursor graphics: + +1. Use the provided CLI tool to capture cursor images: + ```bash + cd crates/cursor-info + cargo run --example cli + ``` + +2. As you hover over different UI elements to trigger different cursors, the tool will display cursor information + +3. For each cursor type, you'll need to: + - Capture the cursor's visual appearance + - Convert it to SVG format + - Measure the hotspot coordinates + - Save to `assets/mac/[cursor-name].svg` + +4. Alternatively, use macOS system tools to extract cursor resources: + ```bash + # Cursor resources may be located in: + # /System/Library/Frameworks/AppKit.framework/Resources/ + # Exact location and extraction method may vary + ``` + +### Step 4: Update the Code + +1. **Update cursor hashes in `src/macos.rs`:** + + Add Tahoe-specific hashes to the `from_hash()` function. You can either: + + - Replace existing hashes if ALL macOS versions now use the new design + - Add additional hash entries if different versions have different designs + + Example of adding alternative hashes: + ```rust + pub fn from_hash(hash: &str) -> Option { + Some(match hash { + // Original hash (pre-Tahoe) + "de2d1f4a81e520b65fd1317b845b00a1c51a4d1f71cca3cd4ccdab52b98d1ac9" => Self::Arrow, + // Tahoe hash (if different) + "NEW_TAHOE_HASH_HERE" => Self::Arrow, + // ... rest of hashes + }) + } + ``` + +2. **Update SVG assets** (if cursor designs changed): + + Replace or add new files in `assets/mac/` with the Tahoe cursor designs + +3. **Update hotspot coordinates** (if needed): + + If cursor visual designs changed, hotspot positions may need adjustment in the `resolve()` function + +### Step 5: Test + +1. **On macOS Tahoe:** + ```bash + cargo test + cargo run --example cli + ``` + + Verify all cursors are detected correctly + +2. **On pre-Tahoe macOS** (if possible): + + Ensure backward compatibility - existing cursors should still work + +3. **Integration test:** + + Run Cap's screen recorder and verify cursor capture works correctly + +### Step 6: Update Documentation + +1. Update this file to mark Tahoe support as complete +2. Update version compatibility notes in README.md +3. Add any version-specific notes if needed + +## Technical Details + +### Cursor Hash Generation + +The hash is generated from the cursor's TIFF image data: +```rust +use sha2::{Sha256, Digest}; + +let hash = format!("{:x}", Sha256::digest(&image_data)); +``` + +### Hotspot Coordinates + +Hotspots are normalized (0.0 to 1.0) relative to cursor dimensions: +- `(0.0, 0.0)` = Top-left corner +- `(1.0, 1.0)` = Bottom-right corner +- `(0.5, 0.5)` = Center + +The hotspot indicates where the "active point" of the cursor is. + +### SVG Format + +Cursor SVGs should: +- Be high-quality vector reproductions +- Match the exact visual appearance of system cursors +- Be appropriately sized (typically 32x32 or 64x64 base dimensions) +- Include proper viewBox attributes + +## Fallback Behavior + +If a Tahoe cursor hash is not recognized, the system will: +1. Return `None` from `from_hash()` +2. Cap will use a default cursor representation +3. Cursor may not match the user's actual cursor appearance + +This is why adding Tahoe support is important for the best user experience. + +## Related Files + +- `src/macos.rs` - Main cursor detection logic +- `assets/mac/` - Cursor SVG assets +- `cursors.html` - Interactive cursor hash viewer +- `examples/cli.rs` - CLI cursor monitoring tool +- `README.md` - General crate documentation + +## Questions or Issues? + +If you encounter any problems while adding Tahoe support: + +1. Check that you're running the latest macOS Tahoe version +2. Verify the cursors.html page loads correctly +3. Ensure SHA-256 hashes are being generated correctly +4. Compare with existing cursor hash patterns + +For questions, please comment on issue #1100 or contact the Cap development team. + +## Completion Checklist + +When Tahoe support is added, update this checklist: + +- [ ] Tahoe cursor hashes extracted and documented +- [ ] Cursor visual changes identified (if any) +- [ ] New cursor hashes added to `src/macos.rs` +- [ ] Cursor SVG assets updated (if needed) +- [ ] Hotspot coordinates verified (if needed) +- [ ] Tests pass on macOS Tahoe +- [ ] Backward compatibility verified on pre-Tahoe macOS +- [ ] Documentation updated +- [ ] PR created and reviewed +- [ ] Issue #1100 closed + +--- + +**Related Issue**: #1100 - Add support for macOS Tahoe Icons +**Created**: 2025-10-08 +**Status**: Awaiting macOS Tahoe cursor assets diff --git a/crates/cursor-info/src/macos.rs b/crates/cursor-info/src/macos.rs index a45c2cfbd8..aa29fb7fc7 100644 --- a/crates/cursor-info/src/macos.rs +++ b/crates/cursor-info/src/macos.rs @@ -2,6 +2,23 @@ use strum::{EnumString, IntoStaticStr}; use crate::{CursorShape, ResolvedCursor}; +// TODO: Add macOS Tahoe cursor support +// macOS Tahoe (macOS 16) introduced a new "Liquid Glass" design language which may include +// updated cursor designs. Once macOS Tahoe is publicly released, the cursor hashes should be +// extracted and added to the from_hash() function below. The process for extracting cursor +// hashes is documented in cursors.html and the README.md file. +// +// Expected Tahoe cursor variants to check: +// - All existing cursor types may have new designs/hashes +// - Potentially new cursor types introduced in Tahoe +// +// To extract Tahoe cursor hashes: +// 1. Run the cursors.html file on a macOS Tahoe system +// 2. Note any new hash values for existing cursors +// 3. Check for any completely new cursor types +// 4. Update the from_hash() function with new/changed hashes +// 5. Update cursor SVG assets if designs have changed + /// macOS Cursors /// https://developer.apple.com/documentation/appkit/nscursor #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, EnumString, IntoStaticStr)] @@ -122,8 +139,17 @@ impl CursorShapeMacOS { /// Derive the cursor type from a hash /// macOS doesn't allow comparing `NSCursor` instances directly so we hash the image data. /// macOS cursor are also resolution-independent so this works. + /// + /// Note: macOS Tahoe (macOS 16) may have different cursor hashes due to the new "Liquid Glass" + /// design language. Once Tahoe is publicly available, new hashes should be extracted and added + /// to this function. Hashes can be extracted using the cursors.html tool on a Tahoe system. pub fn from_hash(hash: &str) -> Option { Some(match hash { + // NOTE: The hashes below are for macOS versions prior to Tahoe (macOS 16) + // TODO: Add macOS Tahoe cursor hashes once available + // If running on macOS Tahoe and cursors aren't being detected, extract new hashes + // using cursors.html and add them here. + "de2d1f4a81e520b65fd1317b845b00a1c51a4d1f71cca3cd4ccdab52b98d1ac9" => Self::Arrow, "ab26ca862492d41355b711c58544687a799dd7ae14cf161959ca524bbc97c322" => { Self::ContextualMenu