markupr 2.1.8

package/docs/EXPORT_FORMATS.md

@@ -0,0 +1,451 @@
+# Export Formats
+
+markupr supports multiple export formats to suit different use cases. This guide covers each format in detail.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Markdown Format](#markdown-format)
+- [PDF Format](#pdf-format)
+- [HTML Format](#html-format)
+- [JSON Format](#json-format)
+- [Export Options](#export-options)
+- [Best Practices](#best-practices)
+
+## Overview
+
+| Format | Best For | File Size | Images |
+|--------|----------|-----------|--------|
+| Markdown | AI assistants, GitHub, documentation | Small | Referenced |
+| PDF | Sharing, printing, archival | Large | Embedded |
+| HTML | Web viewing, email | Medium | Embedded (base64) |
+| JSON | APIs, integrations, automation | Small | Referenced |
+
+## Markdown Format
+
+The Markdown format is optimized for AI coding assistants and follows conventions inspired by [llms.txt](https://llms.txt).
+
+### Structure
+
+```markdown
+# Feedback Report: {Project Name}
+
+> Generated by markupr v0.4.0
+> Date: 2026-02-02 10:30:00
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Duration | 2m 34s |
+| Feedback Items | 5 |
+| Screenshots | 3 |
+| Source | My App - Chrome |
+
+## Feedback Items
+
+### FB-001: Login button not visible on mobile
+
+**Timestamp**: 00:15 | **Type**: Bug | **Confidence**: 95%
+
+> The login button appears to be hidden behind the sticky header when viewing
+> on mobile viewport. Users cannot access the login functionality without
+> scrolling, which is not intuitive.
+
+**Screenshot**: [FB-001.png](./screenshots/FB-001.png)
+
+---
+
+### FB-002: Consider adding social login options
+
+**Timestamp**: 00:45 | **Type**: Feature | **Confidence**: 92%
+
+> It would be helpful to have social login options like Google or GitHub
+> authentication. This is a common pattern that users expect.
+
+---
+
+### FB-003: Form validation errors unclear
+
+**Timestamp**: 01:12 | **Type**: UX | **Confidence**: 89%
+
+> When I enter an invalid email, the error message just says "Invalid input".
+> It should specifically say "Please enter a valid email address" with
+> guidance on the expected format.
+
+**Screenshot**: [FB-003.png](./screenshots/FB-003.png)
+
+---
+
+## Technical Details
+
+- **App Version**: 0.4.0
+- **Platform**: darwin (macOS)
+- **Transcription**: OpenAI Nova-2
+- **Session ID**: session-abc123
+```
+
+### Image Handling
+
+By default, images are stored as separate files and referenced:
+```markdown
+**Screenshot**: [FB-001.png](./screenshots/FB-001.png)
+```
+
+With "Include Images" enabled, images are embedded as base64:
+```markdown
+**Screenshot**: ![FB-001](data:image/png;base64,iVBORw0KGgo...)
+```
+
+### Metadata Block
+
+The Markdown includes a YAML frontmatter block (hidden in rendered view):
+
+```yaml
+---
+markupr_version: 0.4.0
+session_id: session-abc123
+created: 2026-02-02T10:30:00Z
+source: My App - Chrome
+items: 5
+screenshots: 3
+---
+```
+
+### Use Cases
+
+- **Claude, ChatGPT, Cursor**: Paste directly for AI analysis
+- **GitHub Issues**: Copy into issue descriptions
+- **Documentation**: Include in project docs
+- **Notes**: Add to Notion, Obsidian, etc.
+
+## PDF Format
+
+Professional document format for sharing and archival.
+
+### Features
+
+- **Embedded screenshots**: All images included in the PDF
+- **Print-ready**: Proper margins and page breaks
+- **Themes**: Dark or light mode
+- **Typography**: Professional fonts
+
+### Layout
+
+```
+┌──────────────────────────────────────────┐
+│            markupr                   │
+│         Feedback Report                   │
+│                                          │
+│  Project: My App                         │
+│  Date: February 2, 2026                  │
+│  Items: 5 feedback points                │
+├──────────────────────────────────────────┤
+│                                          │
+│  1. Login button not visible             │
+│     ┌────────────────────────┐          │
+│     │   [Screenshot]         │          │
+│     └────────────────────────┘          │
+│                                          │
+│     The login button appears to be...    │
+│                                          │
+│     Type: Bug | Confidence: 95%          │
+│                                          │
+├──────────────────────────────────────────┤
+│  2. Consider adding social login...      │
+│     ...                                  │
+└──────────────────────────────────────────┘
+```
+
+### Theme Options
+
+**Dark Theme**:
+- Dark background (#0f172a)
+- Light text (#f8fafc)
+- Blue accents (#3b82f6)
+- Best for screen viewing
+
+**Light Theme**:
+- White background
+- Dark text (#1e293b)
+- Blue accents (#2563eb)
+- Best for printing
+
+### Use Cases
+
+- **Client presentations**: Professional appearance
+- **Stakeholder reports**: Print-friendly
+- **Archival**: Long-term storage
+- **Email attachments**: Universal compatibility
+
+## HTML Format
+
+Self-contained web page with no external dependencies.
+
+### Features
+
+- **No dependencies**: Single HTML file, works offline
+- **Responsive**: Mobile-friendly layout
+- **Interactive**: Theme toggle, expandable items
+- **Embedded images**: Base64-encoded screenshots
+
+### Structure
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Feedback Report: My App</title>
+  <style>
+    /* All CSS embedded - supports dark/light themes */
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Feedback Report: My App</h1>
+    <div class="metadata">...</div>
+    <button id="theme-toggle">Toggle Theme</button>
+  </header>
+
+  <main>
+    <section class="summary">
+      <table>...</table>
+    </section>
+
+    <section class="feedback-items">
+      <article class="feedback-item">
+        <h2>FB-001: Login button not visible</h2>
+        <div class="meta">Bug | 95% confidence | 00:15</div>
+        <img src="data:image/png;base64,..." alt="Screenshot">
+        <blockquote>The login button appears to be...</blockquote>
+      </article>
+      <!-- More items... -->
+    </section>
+  </main>
+
+  <footer>
+    Generated by markupr v0.4.0
+  </footer>
+
+  <script>
+    /* Theme toggle and interactivity */
+  </script>
+</body>
+</html>
+```
+
+### Interactive Features
+
+- **Theme Toggle**: Switch between dark and light modes
+- **Collapsible Items**: Expand/collapse feedback items
+- **Image Zoom**: Click to enlarge screenshots
+- **Copy Button**: Copy individual items as text
+
+### Use Cases
+
+- **Web sharing**: Host on any web server
+- **Email**: Attach as HTML or inline
+- **Local viewing**: Double-click to open in browser
+- **Collaboration**: Share via Slack, Discord, etc.
+
+## JSON Format
+
+Machine-readable format for integrations and automation.
+
+### Schema
+
+```json
+{
+  "$schema": "https://markupr.app/schemas/export-v1.json",
+  "version": "1.0",
+  "generator": {
+    "name": "markupr",
+    "version": "0.4.0"
+  },
+  "session": {
+    "id": "session-abc123",
+    "startTime": 1706871000000,
+    "endTime": 1706871154000,
+    "duration": 154000,
+    "source": {
+      "id": "window:123:456",
+      "name": "My App - Chrome",
+      "type": "window"
+    }
+  },
+  "summary": {
+    "itemCount": 5,
+    "screenshotCount": 3,
+    "categories": {
+      "bug": 2,
+      "feature": 1,
+      "ux": 2
+    }
+  },
+  "feedbackItems": [
+    {
+      "id": "FB-001",
+      "index": 1,
+      "timestamp": 1706871015000,
+      "relativeTime": 15000,
+      "transcription": "The login button appears to be hidden...",
+      "category": "bug",
+      "confidence": 0.95,
+      "wordCount": 24,
+      "screenshot": {
+        "id": "screenshot-001",
+        "filename": "FB-001.png",
+        "path": "./screenshots/FB-001.png",
+        "width": 1920,
+        "height": 1080,
+        "format": "png",
+        "size": 245678
+      },
+      "annotations": [
+        {
+          "type": "arrow",
+          "x1": 100,
+          "y1": 50,
+          "x2": 200,
+          "y2": 100,
+          "color": "#ef4444"
+        }
+      ]
+    }
+  ],
+  "metadata": {
+    "platform": "darwin",
+    "transcriptionService": "openai",
+    "transcriptionModel": "nova-2",
+    "exportedAt": "2026-02-02T10:35:00.000Z"
+  }
+}
+```
+
+### Field Reference
+
+#### Session Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique session identifier |
+| `startTime` | number | Unix timestamp (ms) of session start |
+| `endTime` | number | Unix timestamp (ms) of session end |
+| `duration` | number | Duration in milliseconds |
+| `source.id` | string | Capture source ID |
+| `source.name` | string | Human-readable source name |
+| `source.type` | string | "screen" or "window" |
+
+#### Feedback Item Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Item ID (e.g., "FB-001") |
+| `index` | number | 1-based index |
+| `timestamp` | number | Unix timestamp (ms) |
+| `relativeTime` | number | Time since session start (ms) |
+| `transcription` | string | Full transcription text |
+| `category` | string | Auto-detected category |
+| `confidence` | number | Transcription confidence (0-1) |
+| `screenshot` | object | Screenshot metadata (if captured) |
+| `annotations` | array | Drawing annotations |
+
+#### Screenshot Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Screenshot ID |
+| `filename` | string | Original filename |
+| `path` | string | Relative path to image |
+| `width` | number | Image width in pixels |
+| `height` | number | Image height in pixels |
+| `format` | string | "png" or "jpeg" |
+| `size` | number | File size in bytes |
+
+### Use Cases
+
+- **API integrations**: Send to issue trackers, project management
+- **Automation**: Process with scripts
+- **Custom tooling**: Build your own viewers/processors
+- **Data analysis**: Aggregate feedback across sessions
+
+### Parsing Example (JavaScript)
+
+```javascript
+const fs = require('fs');
+
+const data = JSON.parse(fs.readFileSync('feedback.json', 'utf8'));
+
+// Get all bugs
+const bugs = data.feedbackItems.filter(item => item.category === 'bug');
+
+// Calculate average confidence
+const avgConfidence = data.feedbackItems.reduce(
+  (sum, item) => sum + item.confidence, 0
+) / data.feedbackItems.length;
+
+// Get items with screenshots
+const withScreenshots = data.feedbackItems.filter(item => item.screenshot);
+
+console.log(`Bugs: ${bugs.length}`);
+console.log(`Average confidence: ${(avgConfidence * 100).toFixed(1)}%`);
+console.log(`Items with screenshots: ${withScreenshots.length}`);
+```
+
+## Export Options
+
+### Include Images
+
+**Available for**: Markdown, PDF, HTML
+
+- **On**: Images are embedded in the export file
+- **Off**: Images are referenced by path (Markdown) or not included (PDF/HTML)
+
+**Trade-offs**:
+- Embedded: Larger file size, but self-contained
+- Referenced: Smaller file, but requires separate image folder
+
+### Theme
+
+**Available for**: PDF, HTML
+
+- **Dark**: Dark background, light text
+- **Light**: Light background, dark text
+
+### Project Name
+
+Customize the title that appears in the export:
+- Default: Captured source name (e.g., "My App - Chrome")
+- Custom: Enter any project name
+
+## Best Practices
+
+### For AI Assistants
+
+1. Use **Markdown** format
+2. Enable **Include Images** (some assistants support image analysis)
+3. Review and edit transcriptions before export
+4. Remove irrelevant items
+
+### For Sharing with Team
+
+1. Use **PDF** for formal reports
+2. Use **HTML** for interactive viewing
+3. Choose **Light theme** for printing
+4. Add project context in the name
+
+### For Integrations
+
+1. Use **JSON** format
+2. Parse with appropriate library
+3. Handle missing fields gracefully
+4. Validate against schema
+
+### For Archival
+
+1. Use **PDF** for long-term storage
+2. Also export **JSON** for data preservation
+3. Keep original screenshots folder
+4. Document session context externally

package/docs/GETTING_STARTED.md

@@ -0,0 +1,236 @@
+# Getting Started with markupr
+
+This guide walks you through setting up markupr for the first time.
+
+## Table of Contents
+
+- [System Requirements](#system-requirements)
+- [Installation](#installation)
+- [First-Time Setup](#first-time-setup)
+- [Obtaining a OpenAI API Key](#obtaining-a-openai-api-key)
+- [Granting Permissions](#granting-permissions)
+- [Your First Recording](#your-first-recording)
+
+## System Requirements
+
+### macOS
+- macOS 10.15 (Catalina) or later
+- Apple Silicon or Intel processor
+- 4 GB RAM minimum
+- 100 MB disk space
+
+### Windows
+- Windows 10 or later
+- x64 processor
+- 4 GB RAM minimum
+- 100 MB disk space
+
+### Linux
+- Ubuntu 18.04+ or equivalent
+- x64 processor
+- 4 GB RAM minimum
+- 100 MB disk space
+
+## Installation
+
+### macOS
+
+1. Download the latest `.dmg` file from the [releases page](https://github.com/eddiesanjuan/markupr/releases)
+2. Open the downloaded DMG file
+3. Drag the markupr icon to your Applications folder
+4. Eject the DMG
+5. Open markupr from your Applications folder
+
+**Note**: On first launch, macOS may show a security warning. Click "Open" to continue, or go to System Preferences > Security & Privacy to allow the app.
+
+### Windows
+
+1. Download the latest `.exe` installer from the [releases page](https://github.com/eddiesanjuan/markupr/releases)
+2. Run the installer
+3. Follow the installation wizard
+4. Launch markupr from the Start menu or desktop shortcut
+
+### Linux
+
+**AppImage:**
+```bash
+# Download the AppImage
+wget https://github.com/eddiesanjuan/markupr/releases/latest/download/markupr.AppImage
+
+# Make it executable
+chmod +x markupr.AppImage
+
+# Run
+./markupr.AppImage
+```
+
+**Debian/Ubuntu:**
+```bash
+# Download and install
+wget https://github.com/eddiesanjuan/markupr/releases/latest/download/markupr.deb
+sudo dpkg -i markupr.deb
+sudo apt-get install -f  # Install dependencies if needed
+```
+
+## First-Time Setup
+
+When you launch markupr for the first time, the onboarding wizard will guide you through:
+
+1. **Welcome** - Introduction to markupr
+2. **Permissions** - Granting required system permissions
+3. **API Key** - Configuring your OpenAI API key
+4. **Quick Tour** - Learning the basic workflow
+
+You can skip the wizard and configure settings manually, but we recommend completing it.
+
+## Obtaining a OpenAI API Key
+
+markupr uses OpenAI for real-time speech-to-text transcription. Here's how to get your API key:
+
+### Step 1: Create a OpenAI Account
+
+1. Go to [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
+2. Click "Sign Up" (or "Sign In" if you have an account)
+3. Complete the registration process
+
+### Step 2: Create an API Key
+
+1. Once logged in, go to **API Keys** in the left sidebar
+2. Click **Create a New API Key**
+3. Give your key a descriptive name (e.g., "markupr")
+4. Select the following permissions:
+   - **Usage** (required for transcription)
+5. Click **Create Key**
+6. **Copy the key immediately** - you won't be able to see it again!
+
+### Step 3: Add the Key to markupr
+
+1. Open markupr
+2. Go to **Settings** (`Cmd+,` on macOS, `Ctrl+,` on Windows)
+3. Navigate to **Advanced** > **Transcription Service**
+4. Paste your API key in the input field
+5. Click **Test Connection** to verify
+6. You should see "API key verified and saved securely"
+
+### OpenAI Free Tier
+
+OpenAI offers a generous free tier:
+- **200 hours** of transcription per month
+- **No credit card required** to start
+- Perfect for individual developers
+
+For higher volume usage, OpenAI offers paid plans starting at pay-as-you-go pricing.
+
+## Granting Permissions
+
+markupr requires certain system permissions to function properly.
+
+### macOS Permissions
+
+#### Microphone Access
+
+markupr needs microphone access to capture your voice narration.
+
+1. When prompted, click **OK** to allow microphone access
+2. If you denied access, go to:
+   - System Preferences > Security & Privacy > Privacy > Microphone
+   - Check the box next to markupr
+
+#### Screen Recording
+
+markupr needs screen recording permission to capture screenshots.
+
+1. When prompted, click **Open System Preferences**
+2. Go to Security & Privacy > Privacy > Screen Recording
+3. Check the box next to markupr
+4. **Restart markupr** for the change to take effect
+
+#### Accessibility (Optional)
+
+For global hotkeys to work in all applications:
+
+1. Go to System Preferences > Security & Privacy > Privacy > Accessibility
+2. Click the lock icon and enter your password
+3. Check the box next to markupr
+
+### Windows Permissions
+
+Windows typically handles permissions automatically. If you encounter issues:
+
+1. Right-click on markupr in the Start menu
+2. Select "Run as administrator" (for first run only)
+3. Follow any Windows Security prompts
+
+### Linux Permissions
+
+Depending on your distribution, you may need to:
+
+```bash
+# Add your user to the audio group for microphone access
+sudo usermod -a -G audio $USER
+
+# Log out and log back in for changes to take effect
+```
+
+## Your First Recording
+
+Now that everything is set up, let's capture your first feedback!
+
+### Step 1: Start Recording
+
+Press the global hotkey:
+- **macOS**: `Cmd+Shift+F`
+- **Windows/Linux**: `Ctrl+Shift+F`
+
+### Step 2: Select a Source
+
+The Window Selector will appear. Choose what to capture:
+- **Entire Screen** - Capture everything on one monitor
+- **Specific Window** - Capture just one application window
+
+Click on your selection to start.
+
+### Step 3: Narrate Your Feedback
+
+Start speaking! Some tips:
+- Speak naturally and clearly
+- Pause briefly when you want a screenshot captured
+- The live transcription preview shows what markupr hears
+
+### Step 4: Screenshots
+
+markupr captures screenshots automatically when you pause speaking. You can also:
+- Press `Cmd+Shift+S` (or `Ctrl+Shift+S`) to manually capture
+- Watch the screenshot count in the overlay
+
+### Step 5: Stop Recording
+
+Press the hotkey again (`Cmd+Shift+F` or `Ctrl+Shift+F`) to stop.
+
+### Step 6: Review and Export
+
+After stopping:
+1. The Session Review panel opens
+2. Review your feedback items
+3. Edit or delete items as needed
+4. Click **Copy to Clipboard** or choose an export format
+
+### Step 7: Use Your Feedback
+
+Paste the copied feedback into your AI assistant:
+- Claude
+- ChatGPT
+- Cursor
+- GitHub Copilot
+
+The Markdown format is optimized for AI consumption.
+
+## Next Steps
+
+- [Configure settings](CONFIGURATION.md) to customize markupr
+- [Learn keyboard shortcuts](KEYBOARD_SHORTCUTS.md) for efficient workflows
+- [Explore export formats](EXPORT_FORMATS.md) for different use cases
+
+## Troubleshooting
+
+Having issues? Check our [Troubleshooting Guide](TROUBLESHOOTING.md) for common solutions.