Restore three-button capture interface: Share Entire Screen, Snip, Cancel

tools/screen-capture/README.md

@@ -0,0 +1,147 @@
+# Screen Capture Tool
+
+A standalone utility for capturing screenshots from user's screen using the native Browser Screen Capture API.
+
+## Features
+
+- 📸 Capture screenshots from user-selected screen/window
+- 🎯 No external dependencies
+- ⚡ Returns canvas for flexible post-processing
+- 🛡️ Graceful error handling
+- ♿ Respects user permissions
+
+## Installation
+
+Copy the `screen-capture` folder to your project:
+
+```
+your-project/
+├── tools/
+│   └── screen-capture/
+│       ├── index.js
+│       └── README.md
+```
+
+## Usage
+
+### Basic Screenshot Capture
+
+```javascript
+import { captureScreenshot } from './tools/screen-capture/index.js';
+
+const canvas = await captureScreenshot();
+if (canvas) {
+  // Canvas is ready for use
+  // Convert to File, display, or manipulate further
+}
+```
+
+### Convert to File
+
+```javascript
+import { captureScreenshot, canvasToFile } from './tools/screen-capture/index.js';
+
+const canvas = await captureScreenshot();
+if (canvas) {
+  const file = await canvasToFile(canvas, 'my-screenshot.png');
+  // Use file with FormData, attachments, etc.
+}
+```
+
+### One-liner with Blob
+
+```javascript
+const canvas = await captureScreenshot();
+canvas?.toBlob((blob) => {
+  const file = new File([blob], `screenshot-${Date.now()}.png`, { type: 'image/png' });
+  // Use file...
+});
+```
+
+## API Reference
+
+### `captureScreenshot()`
+
+**Returns:** `Promise<Canvas | null>`
+
+Opens native browser dialog for user to select screen/window to capture. Returns a canvas element containing the screenshot, or null if user cancels or error occurs.
+
+**Example:**
+```javascript
+const canvas = await captureScreenshot();
+```
+
+### `canvasToFile(canvas, filename?)`
+
+**Parameters:**
+- `canvas` (Canvas): Canvas element to convert
+- `filename` (string, optional): Custom filename. Defaults to `screenshot-{timestamp}.png`
+
+**Returns:** `Promise<File>`
+
+Converts canvas to PNG File object for easy handling in file uploads or attachments.
+
+**Example:**
+```javascript
+const file = await canvasToFile(canvas, 'custom-name.png');
+```
+
+## Browser Support
+
+Requires browsers supporting the Screen Capture API:
+- Chrome 72+
+- Edge 79+
+- Firefox 66+
+- Safari 13+
+
+Note: User must grant permission for each capture request.
+
+## Error Handling
+
+The tool gracefully handles:
+- User cancellation of the capture dialog
+- Browser permission denial
+- Browser incompatibility
+- Missing canvas/video support
+
+All errors are logged to console and return null.
+
+## Examples
+
+### React Component
+
+```jsx
+import { captureScreenshot, canvasToFile } from './tools/screen-capture/index.js';
+
+export function ScreenshotButton() {
+  const handleCapture = async () => {
+    const canvas = await captureScreenshot();
+    if (canvas) {
+      const file = await canvasToFile(canvas);
+      console.log('Screenshot captured:', file.name);
+    }
+  };
+
+  return <button onClick={handleCapture}>Take Screenshot</button>;
+}
+```
+
+### With Form Submission
+
+```javascript
+import { captureScreenshot, canvasToFile } from './tools/screen-capture/index.js';
+
+const canvas = await captureScreenshot();
+if (canvas) {
+  const file = await canvasToFile(canvas);
+  
+  const formData = new FormData();
+  formData.append('screenshot', file);
+  
+  await fetch('/api/upload', { method: 'POST', body: formData });
+}
+```
+
+## License
+
+MIT - Use freely in your projects