jyapayne/screenshot-chrome-extension
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: added feature spec

Browse source
This commit is contained in:
KarthiDreamr 2025-08-13 21:03:22 +05:30
commit 3342ba7e15
3 changed files with 309 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

187
.kiro/specs/save-to-pc-toggle/design.md Normal file
View file

@ -0,0 +1,187 @@
# Design Document
## Overview
The save to PC toggle feature will be implemented as an additional setting in the extension popup, positioned alongside the existing clipboard toggle. The feature will modify the existing screenshot capture workflow to conditionally perform file downloads based on user preference. The implementation will ensure that users can independently control both clipboard copying and file downloading, providing maximum flexibility in their screenshot workflow.
## Architecture
The feature will be implemented across three main components:
1. **Popup UI Enhancement**: Add toggle control and persistence logic
2. **Content Script Integration**: Modify screenshot capture to conditionally download files
3. **Storage Management**: Extend existing preference storage system
4. **Validation Logic**: Ensure at least one output method is selected
The save to PC functionality will be implemented as a conditional enhancement to the existing screenshot workflow, maintaining backward compatibility while providing new flexibility.
## Components and Interfaces
### Popup Interface (`popup.html` & `popup.js`)
**New UI Elements:**
- Toggle switch control for "Save to PC" option
- Positioned above the clipboard toggle for logical grouping
- Consistent styling with existing controls
- Warning message when both toggles are disabled
**Storage Integration:**
- Extend existing `chrome.storage.sync` usage to include `saveToPc` preference
- Default value: `true` (enabled by default to maintain existing behavior)
- Load and save preferences alongside existing background and clipboard preferences
**Validation Logic:**
- Check that at least one output method (save to PC or clipboard) is enabled
- Display warning message when both are disabled
- Prevent screenshot capture when no output method is selected
**Message Passing:**
- Include `saveToPc` setting in the `startSelector` message to content script
- No changes needed to existing message structure, just additional property
### Content Script Enhancement (`content.js`)
**ScreenshotSelector Class Modifications:**
- Add `saveToPc` property to constructor
- Modify `init()` method to accept and store save to PC preference
- Enhance `captureElement()` method to conditionally perform file downloads
**Conditional Download Implementation:**
```javascript
// In captureElement method, replace automatic download with conditional logic
if (this.saveToPc) {
const link = document.createElement('a');
link.href = canvas.toDataURL('image/png');
link.download = `screenshot-${new Date().toISOString().slice(0, 19).replace(/[:.]/g, '-')}.png`;
link.click();
}
```
**User Feedback Enhancement:**
- Update success messages to reflect which operations were performed
- Handle cases where no output method is selected (should not occur due to popup validation)
### User Feedback System
**Success States:**
- "Screenshot saved and copied to clipboard!" - when both operations succeed
- "Screenshot saved!" - when only save to PC is enabled and succeeds
- "Screenshot copied to clipboard!" - when only clipboard is enabled and succeeds
- "Screenshot captured!" - fallback message for edge cases
**Error States:**
- "Please enable at least one output method (Save to PC or Copy to Clipboard)" - when both are disabled
- Existing clipboard error messages remain unchanged
**Loading States:**
- Update loading message to reflect enabled operations
- "Capturing screenshot..." - when only save to PC is enabled
- "Capturing screenshot and preparing for clipboard..." - when only clipboard is enabled
- "Capturing screenshot and preparing for clipboard..." - when both are enabled (clipboard preparation is the longer operation)
## Data Models
### Settings Storage Schema
```javascript
{
backgroundPreference: 'black' | 'transparent' | 'white',
copyToClipboard: boolean,
saveToPc: boolean // New addition
}
```
### Message Interface Extension
```javascript
// startSelector message
{
action: 'startSelector',
background: string,
copyToClipboard: boolean,
saveToPc: boolean // New addition
}
```
## Error Handling
### Validation Errors
- Prevent screenshot capture when both save to PC and clipboard are disabled
- Display clear error message in popup when no output method is selected
- Provide guidance on enabling at least one option
### Download Failures
- Handle file download failures gracefully (though these are rare in modern browsers)
- Ensure clipboard operations continue even if download fails (when both are enabled)
- Provide specific error messages for download-related issues
### Backward Compatibility
- Ensure existing users see no change in behavior (save to PC enabled by default)
- Handle cases where preference is not yet set in storage
- Maintain existing error handling for clipboard operations
## Testing Strategy
### Unit Testing Approach
- Test preference storage and retrieval for save to PC setting
- Verify message passing includes new saveToPc property
- Test validation logic for ensuring at least one output method is enabled
- Mock file download operations for testing conditional download logic
### Integration Testing
- Test complete workflow: toggle setting → capture screenshot → verify file download behavior
- Test all four combinations of save to PC and clipboard settings
- Verify error handling when both options are disabled
- Test preference persistence across browser sessions
### User Experience Testing
- Verify toggle state persistence across browser sessions
- Test visual feedback for different operation combinations
- Confirm tooltip and help text clarity
- Test warning messages when both toggles are disabled
## Implementation Considerations
### Performance Impact
- No performance impact when save to PC is enabled (existing behavior)
- Slight performance improvement when save to PC is disabled (no file creation)
- No impact on clipboard operations
### Security Considerations
- File downloads use existing browser download mechanisms
- No new security concerns introduced
- Maintains existing security model for clipboard operations
### Accessibility
- Save to PC toggle will include proper ARIA labels
- Keyboard navigation support for toggle control
- Screen reader compatible success/error messages
- Warning messages will be announced to screen readers
### User Experience Design
- Logical grouping of output method toggles
- Clear visual hierarchy with save to PC above clipboard (primary → secondary)
- Consistent styling with existing UI elements
- Intuitive default settings (both enabled initially)
## Browser Compatibility
### File Download Support
- File downloads work in all modern browsers
- No fallback needed as this is core browser functionality
- Existing implementation already handles download edge cases
### Storage and UI
- Uses existing chrome.storage.sync API (already implemented)
- Toggle UI uses existing CSS patterns
- No new browser API dependencies
## Migration Strategy
### Existing Users
- Default `saveToPc` to `true` when preference doesn't exist
- No change in behavior for existing users
- Seamless upgrade experience
### New Users
- Both save to PC and clipboard enabled by default
- Provides full functionality out of the box
- Users can customize based on their workflow preferences

51
.kiro/specs/save-to-pc-toggle/requirements.md Normal file
View file

@ -0,0 +1,51 @@
# Requirements Document
## Introduction
This feature adds a save to PC toggle option to the Full Screenshot Selector extension, allowing users to choose whether captured screenshots should be automatically downloaded as files to their computer. This provides users with more flexibility in how they handle their screenshots, enabling them to use only the clipboard functionality without cluttering their downloads folder with files they may not need.
## Requirements
### Requirement 1
**User Story:** As a user of the screenshot extension, I want to toggle whether screenshots are saved to my PC, so that I can avoid downloading files when I only need to paste the image elsewhere.
#### Acceptance Criteria
1. WHEN the popup is opened THEN the system SHALL display a toggle control for "Save to PC"
2. WHEN the user toggles the save to PC option THEN the system SHALL save this preference to browser storage
3. WHEN the extension is reopened THEN the system SHALL restore the previously saved save to PC preference
4. WHEN a screenshot is captured AND save to PC is enabled THEN the system SHALL download the file as before
5. WHEN a screenshot is captured AND save to PC is disabled THEN the system SHALL NOT download any file
### Requirement 2
**User Story:** As a user, I want clear visual feedback about the save to PC feature, so that I understand when files will be downloaded and when they won't.
#### Acceptance Criteria
1. WHEN the save to PC toggle is enabled THEN the system SHALL display visual indication of the enabled state
2. WHEN a screenshot is captured with save to PC enabled THEN the system SHALL show a success message indicating the download
3. WHEN a screenshot is captured with save to PC disabled THEN the system SHALL show a success message without mentioning download
4. WHEN hovering over the save to PC toggle THEN the system SHALL display helpful tooltip text
### Requirement 3
**User Story:** As a user, I want the save to PC feature to work independently of the clipboard feature, so that I can choose any combination of saving and copying that suits my workflow.
#### Acceptance Criteria
1. WHEN both save to PC and copy to clipboard are enabled THEN the system SHALL perform both operations
2. WHEN only save to PC is enabled THEN the system SHALL only download the file
3. WHEN only copy to clipboard is enabled THEN the system SHALL only copy to clipboard
4. WHEN both features are disabled THEN the system SHALL show an error message and not capture the screenshot
### Requirement 4
**User Story:** As a user, I want sensible default settings for the save to PC feature, so that the extension works intuitively without requiring configuration.
#### Acceptance Criteria
1. WHEN the extension is used for the first time THEN the save to PC option SHALL be enabled by default
2. WHEN upgrading from a previous version THEN the save to PC option SHALL be enabled by default to maintain existing behavior
3. WHEN both save to PC and clipboard options are available THEN users SHALL be able to configure them independently

71
.kiro/specs/save-to-pc-toggle/tasks.md Normal file
View file

@ -0,0 +1,71 @@
# Implementation Plan
- [ ] 1. Add save to PC toggle UI to popup
- Add HTML toggle control above the clipboard toggle in popup.html
- Style the toggle control to match existing UI design patterns
- Include proper ARIA labels and accessibility attributes for the toggle
- Position the save to PC toggle logically above clipboard toggle
- _Requirements: 1.1, 2.1, 2.4_
- [ ] 2. Implement save to PC preference storage in popup
- Extend existing storage logic in popup.js to handle saveToPc preference
- Set default value to true to maintain existing behavior for current users
- Load saved save to PC preference on popup initialization
- Save save to PC preference changes to chrome.storage.sync
- _Requirements: 1.2, 1.3, 4.1, 4.2_
- [ ] 3. Add validation logic for output method selection
- Create validation function to ensure at least one output method is enabled
- Display warning message in popup when both save to PC and clipboard are disabled
- Prevent screenshot capture when no output method is selected
- Update start button state based on validation results
- _Requirements: 3.4_
- [ ] 4. Update message passing to include save to PC setting
- Modify startSelector message in popup.js to include saveToPc property
- Update content script message handler to receive and store save to PC preference
- Ensure backward compatibility with existing message structure
- _Requirements: 1.1, 1.4_
- [ ] 5. Implement conditional file download in content script
- Modify captureElement method in ScreenshotSelector class to conditionally download files
- Wrap existing download logic in conditional check for saveToPc preference
- Ensure canvas generation still occurs regardless of download preference (needed for clipboard)
- Maintain existing download filename generation and format
- _Requirements: 1.4, 1.5, 3.1, 3.2_
- [ ] 6. Update user feedback messages for different operation combinations
- Modify success messages to reflect which operations were performed
- Create specific messages for save-only, clipboard-only, and both operations
- Update loading messages to reflect enabled operations
- Ensure error messages are appropriate for each operation combination
- _Requirements: 2.2, 2.3, 3.1, 3.2, 3.3_
- [ ] 7. Add tooltip and help text for save to PC toggle
- Implement tooltip showing save to PC feature explanation
- Add help text explaining the relationship between save to PC and clipboard features
- Ensure tooltip is accessible and keyboard navigable
- Include information about default behavior and workflow flexibility
- _Requirements: 2.4_
- [ ] 8. Implement warning system for disabled output methods
- Create visual warning when both save to PC and clipboard toggles are disabled
- Display clear guidance on enabling at least one output method
- Make warning accessible to screen readers
- Update warning state dynamically as toggles change
- _Requirements: 3.4_
- [ ] 9. Test all combinations of save to PC and clipboard settings
- Write test cases for save-only mode (saveToPc: true, clipboard: false)
- Write test cases for clipboard-only mode (saveToPc: false, clipboard: true)
- Write test cases for both enabled (saveToPc: true, clipboard: true)
- Write test cases for validation when both disabled (saveToPc: false, clipboard: false)
- Verify preference persistence across browser sessions for all combinations
- _Requirements: 3.1, 3.2, 3.3, 3.4, 4.3_
- [ ] 10. Test backward compatibility and migration
- Test behavior when saveToPc preference doesn't exist in storage (new installation)
- Test behavior when upgrading from version without saveToPc preference
- Verify that existing users maintain current behavior (files still download by default)
- Test that new users get both features enabled by default
- _Requirements: 4.1, 4.2_