Skip to content

Commit b8d1e78

Browse files
bartwischbartwisch
committed
docs: update documentation to match current implementation
1 parent 4d8c639 commit b8d1e78

File tree

9 files changed

+429
-0
lines changed

9 files changed

+429
-0
lines changed

‎markups/concept.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# WindPix - Screenshot Integration for Windsurf
2+
3+
## Overview
4+
WindPix is a macOS utility that streamlines the process of sharing screenshots within the Windsurf application. It automates the workflow of capturing, copying, and sending screenshots to the LLM chat interface.
5+
6+
## Core Functionality
7+
1. **Screenshot Capture**
8+
- Triggered by global hotkey (⌘P)
9+
- Supports both full screen and area selection
10+
- Screenshot control panel for accept/redo/cancel
11+
12+
2. **Windsurf Integration**
13+
- Optional automatic chat window focus
14+
- Automatic clipboard management
15+
- Automatic screenshot submission
16+
17+
## Technical Implementation
18+
1. **Screenshot Mechanism**
19+
- Uses native macOS screenshot capabilities
20+
- Supports area selection and full screen
21+
- Built-in screenshot preview and control
22+
23+
2. **Automation Flow**
24+
- Configurable focus chat option
25+
- Automatic Windsurf launch
26+
- Auto-close with Windsurf option
27+
28+
## User Experience
29+
- System tray menu for easy access
30+
- Configurable settings via menu
31+
- Visual feedback through control panel
32+
- How-to instructions built in
33+
34+
## Current Features
35+
- Global hotkey (⌘P)
36+
- Area selection toggle
37+
- Focus chat toggle
38+
- Auto-close with Windsurf toggle
39+
- Built-in instructions
40+
- System tray controls

‎markups/distribution.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Distributing WindPix
2+
3+
To distribute WindPix to other users, follow these steps:
4+
5+
## For Developers (Creating the Distribution)
6+
7+
1. Build the release version:
8+
```bash
9+
cd WindPixMVP
10+
swift build -c release
11+
```
12+
13+
2. Create an App Bundle:
14+
```bash
15+
# Create the app bundle structure
16+
mkdir -p WindPix.app/Contents/MacOS
17+
mkdir -p WindPix.app/Contents/Resources
18+
19+
# Copy the built executable
20+
cp .build/release/WindPixMVP WindPix.app/Contents/MacOS/WindPix
21+
22+
# Copy instructions.md to Resources
23+
cp ../instructions.md WindPix.app/Contents/Resources/
24+
```
25+
26+
3. Create Info.plist:
27+
Create a file at `WindPix.app/Contents/Info.plist` with the following content:
28+
```xml
29+
<?xml version="1.0" encoding="UTF-8"?>
30+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
31+
<plist version="1.0">
32+
<dict>
33+
<key>CFBundleExecutable</key>
34+
<string>WindPix</string>
35+
<key>CFBundleIdentifier</key>
36+
<string>com.hugo.windpix</string>
37+
<key>CFBundleName</key>
38+
<string>WindPix</string>
39+
<key>CFBundlePackageType</key>
40+
<string>APPL</string>
41+
<key>CFBundleShortVersionString</key>
42+
<string>1.0</string>
43+
<key>LSMinimumSystemVersion</key>
44+
<string>10.15</string>
45+
<key>LSUIElement</key>
46+
<true/>
47+
</dict>
48+
</plist>
49+
```
50+
51+
4. Create a ZIP archive:
52+
```bash
53+
zip -r WindPix.zip WindPix.app
54+
```
55+
56+
## For Users (Installing the App)
57+
58+
1. Download the WindPix.zip file
59+
2. Extract the ZIP file
60+
3. Move WindPix.app to your Applications folder
61+
4. When first launching the app:
62+
- Right-click on WindPix.app and select "Open"
63+
- Click "Open" in the security dialog that appears
64+
- Grant the necessary permissions when prompted:
65+
* Screen Recording (for taking screenshots)
66+
* Accessibility (for keyboard shortcuts)
67+
68+
## Requirements
69+
70+
- macOS 10.15 or later
71+
- Windsurf IDE installed
72+
73+
## Notes
74+
75+
- The app is currently unsigned, so users will need to explicitly allow it to run
76+
- The app requires Windsurf IDE to be running
77+
- Make sure to grant all requested permissions for full functionality
78+
79+
## Support
80+
81+
For support or questions, contact: [email protected]

‎markups/featurelist.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
- always automatically focus on cascade chat window

‎markups/icon_instructions.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Creating an App Icon for WindPix
2+
3+
To create a proper app icon, you'll need to create images in the following sizes and save them in the `AppIcon.iconset` folder:
4+
5+
1. Required icon files and sizes:
6+
- icon_16x16.png (16×16)
7+
- [email protected] (32×32)
8+
- icon_32x32.png (32×32)
9+
- [email protected] (64×64)
10+
- icon_128x128.png (128×128)
11+
- [email protected] (256×256)
12+
- icon_256x256.png (256×256)
13+
- [email protected] (512×512)
14+
- icon_512x512.png (512×512)
15+
- [email protected] (1024×1024)
16+
17+
2. After creating these images, convert them to .icns:
18+
```bash
19+
cd WindPixMVP
20+
iconutil -c icns AppIcon.iconset
21+
```
22+
23+
3. Add to Info.plist:
24+
The following entry will be added to Info.plist:
25+
```xml
26+
<key>CFBundleIconFile</key>
27+
<string>AppIcon</string>
28+
```
29+
30+
## Icon Design Guidelines
31+
32+
1. Keep it simple and recognizable even at small sizes
33+
2. Use the macOS icon grid for proper proportions
34+
3. Consider both light and dark backgrounds
35+
4. Make sure the icon looks good in both color and monochrome
36+
37+
## Tools for Creating Icons
38+
39+
You can use these tools to create your icon:
40+
- Adobe Photoshop
41+
- Sketch
42+
- Figma
43+
- Pixelmator Pro
44+
- Icon Set Creator (Mac App Store)
45+
46+
## Testing the Icon
47+
48+
After creating the icon:
49+
1. Build the app bundle
50+
2. Copy AppIcon.icns to WindPix.app/Contents/Resources/
51+
3. Update Info.plist
52+
4. The icon should appear in Finder and the Dock

‎markups/idea.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Initial Idea vs Current Implementation
2+
3+
## Original Idea
4+
A program for Mac that creates a screenshot with a shortcut.
5+
The screenshot is copied to the clipboard.
6+
Then the key combination "cmd + l" is pressed to focus the chat window in the "windsurf" program.
7+
After a 1-second delay, the image from the clipboard is pasted into the chat window using "cmd + v".
8+
After another 1-second delay, the ENTER key is pressed to forward the image to the LLM.
9+
10+
## Current Implementation
11+
The idea has evolved into a more sophisticated application with:
12+
- System tray presence with wind icon
13+
- Configurable screenshot behavior (area/full screen)
14+
- Optional chat window focus
15+
- Screenshot preview and control panel
16+
- Automatic Windsurf launch
17+
- Auto-close capability

‎markups/instructions.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Welcome to WindPix - Your Screenshot Companion for Windsurf
2+
3+
WindPix makes it easy to include screenshots in your Windsurf workflow, helping you communicate more effectively with the LLM.
4+
5+
## Getting Started
6+
1. Launch WindPix - you'll see a wind icon in your system tray
7+
2. WindPix will automatically launch Windsurf if it's not running
8+
3. Click the wind icon to access settings and options
9+
10+
## Taking Screenshots
11+
1. Press ⌘P to initiate a screenshot
12+
2. If area selection is enabled, select the area you want to capture
13+
3. In the control panel that appears:
14+
- Click "Accept" to send the screenshot to Windsurf
15+
- Click "Redo" to take another screenshot
16+
- Click "Cancel" to abort
17+
18+
## Configuration Options
19+
Access these by clicking the wind icon:
20+
- **Use Area Selection**: Toggle between area selection and full screen
21+
- **Focus Chat Before Paste**: Automatically focus the chat window
22+
- **Auto-close with Windsurf**: Close WindPix when Windsurf closes
23+
24+
## Required Permissions
25+
WindPix needs these permissions to function:
26+
- Screen Recording (for screenshots)
27+
- Accessibility (for keyboard simulation)
28+
- Input Monitoring (for hotkey)
29+
30+
## Tips
31+
- You can take multiple screenshots for one prompt
32+
- Use area selection for precise captures
33+
- Keep Windsurf's chat window visible for best results
34+
35+
## Support
36+
For issues or suggestions, visit:
37+
https://github.com/bartwisch/windpix/issues
38+
39+
Created by Hugo ([email protected])

‎markups/mvp.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# WindPix MVP Status
2+
3+
## Implemented Features
4+
1. Global hotkey (⌘P)
5+
2. Area selection and full screen modes
6+
3. Screenshot control panel
7+
- Accept/Redo/Cancel options
8+
4. System tray menu
9+
- Configuration options
10+
- How-to instructions
11+
5. Automatic Windsurf integration
12+
- Auto-launch
13+
- Optional chat focus
14+
- Auto-close capability
15+
16+
## Current Tech Stack
17+
- Swift command-line tool with AppKit UI
18+
- Global hotkey using Carbon API
19+
- Screenshot capture using native APIs
20+
- System tray integration
21+
- Window management
22+
23+
## Implemented Functionality
24+
25+
1. **Core Application**
26+
```swift
27+
// AppDelegate manages:
28+
- System tray icon and menu
29+
- Windsurf monitoring
30+
- Configuration options
31+
- Instructions window
32+
```
33+
34+
2. **Permissions**
35+
✓ Screen Recording
36+
✓ Accessibility
37+
✓ Input Monitoring
38+
39+
## Current Status
40+
- MVP is fully functional
41+
- Core features implemented
42+
- Basic UI through system tray
43+
- Error handling in place
44+
- Configuration options available
45+
46+
## Completed MVP Goals
47+
✓ Screenshot capture with hotkey
48+
✓ Preview and control panel
49+
✓ System tray presence
50+
✓ Basic settings
51+
✓ Windsurf integration
52+
53+
## Future Enhancements
54+
- Custom keyboard shortcuts
55+
- Enhanced error notifications
56+
- Installation package
57+
- Auto-updates
58+
- Multiple monitor improvements

‎markups/techstack.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# WindPix Technical Stack
2+
3+
## Core Technologies
4+
5+
### Programming Language
6+
- **Swift 5.9+**
7+
- Native macOS development
8+
- System API integration
9+
- Clean and modern syntax
10+
- Type-safe operations
11+
12+
### Frameworks Used
13+
- **AppKit**
14+
- System tray implementation
15+
- Window and panel management
16+
- Menu creation and handling
17+
- Basic UI components
18+
19+
- **Foundation**
20+
- Core functionality
21+
- File operations
22+
- Timer management
23+
- Error handling
24+
25+
- **Carbon**
26+
- Global hotkey registration
27+
- Keyboard event handling
28+
29+
### System Integration
30+
- **Screenshot Capabilities**
31+
- Native screenshot commands
32+
- Area selection support
33+
- Clipboard management
34+
35+
- **Window Management**
36+
- Windsurf window detection
37+
- Focus management
38+
- Event simulation
39+
40+
### Development Tools
41+
- **Xcode**
42+
- Development environment
43+
- Debugging tools
44+
- Performance monitoring
45+
46+
### Distribution
47+
- **GitHub**
48+
- Version control
49+
- Issue tracking
50+
- Release management
51+
52+
### Current Architecture
53+
- **AppDelegate**
54+
- Application lifecycle
55+
- Menu management
56+
- Configuration handling
57+
58+
- **HotkeyManager**
59+
- Keyboard event handling
60+
- Screenshot automation
61+
- Window management
62+
63+
- **ScreenshotControlPanel**
64+
- User interface for preview
65+
- Action handling
66+
- Visual feedback
67+
68+
## System Requirements
69+
- macOS 13.0 (Ventura) or newer
70+
- 20MB disk space
71+
- Minimal RAM usage
72+
73+
## Development Environment Setup
74+
1. Install Xcode from Mac App Store
75+
2. Install command line tools:
76+
```bash
77+
xcode-select --install
78+
```
79+
3. Clone repository and open in Xcode
80+
81+
## Testing Framework
82+
- **XCTest**
83+
- Unit testing
84+
- UI testing
85+
- Performance testing

0 commit comments

Comments
 (0)