markupr 2.1.8

package/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to markupr will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-02-04
+
+### Highlights
+**markupr Initial Public Release** - Voice-to-AI feedback for developers. Free and open source.
+
+### Added
+- **Bulletproof State Machine**: 7-state finite state machine with watchdog timer - can never get stuck
+- **Menu Bar Native**: Runs entirely from the menu bar (no dock icon)
+- **Three-Tier Transcription**: OpenAI (premium) -> Whisper (default) -> Timer fallback
+- **Crash Recovery**: 5-second auto-save ensures no work is lost
+- **Offline Mode**: Local Whisper transcription works without internet
+- **Platform-Aware Hotkeys**: Cmd on Mac, Ctrl on Windows - just works
+- **Donate Button**: Rotating messages for supporting the developer
+- **Windows Taskbar Integration**: Overlay icons and toolbar buttons
+
+### Changed
+- Default transcription now uses local Whisper (no API key required)
+- Improved documentation with comprehensive guides
+- Enhanced stability across all platforms
+
+### Technical
+- State machine: IDLE -> STARTING -> RECORDING -> STOPPING -> PROCESSING -> REVIEWING -> EXPORTING
+- Watchdog monitors state transitions with configurable timeouts
+- Recovery manager handles unexpected exits gracefully
+
+## [0.4.0] - 2026-02-02
+
+### Added
+- **Export Options**: PDF, HTML, and JSON export formats
+- **AI-Powered Categorization**: Automatic feedback categorization (Bug, Feature, UX)
+- **Crash Recovery**: Automatic session recovery after unexpected crashes
+- **Auto-Updater**: Seamless application updates with release notes
+- **Keyboard Shortcuts Panel**: In-app cheatsheet with customization
+- **Session History Browser**: View and manage past recording sessions
+- **Multi-Monitor Support**: Full support for multiple displays with source preview
+- **Screenshot Annotations**: Arrow, circle, rectangle, freehand, and text tools
+- **Audio Waveform Visualization**: Real-time audio level display
+- **Countdown Timer**: Optional countdown before recording starts
+- **Clarification Questions**: AI-generated follow-up questions for unclear feedback
+- **Native macOS Menu Bar**: Full menu bar integration
+
+### Changed
+- Improved Settings panel with live preview
+- Enhanced onboarding wizard with better guidance
+- Better error messages and user feedback
+- Upgraded to Electron 28
+
+### Fixed
+- Fixed screenshot timing during rapid speech
+- Fixed hotkey registration on Windows
+- Fixed memory leak during long sessions
+- Fixed clipboard copy on some macOS versions
+
+## [0.3.0] - 2026-01-15
+
+### Added
+- **Real-time Transcription Preview**: See transcription as you speak
+- **Intelligent Screenshot Timing**: Voice activity detection triggers captures
+- **Tray Icon States**: Visual feedback for idle/recording/processing/error
+- **Settings Panel**: Comprehensive configuration UI
+- **Session Review**: Edit, reorder, and delete feedback items before export
+- **Theme System**: Dark, light, and system theme options
+
+### Changed
+- Improved OpenAI integration with better error handling
+- Enhanced Markdown output format for AI consumption
+- Better screenshot compression
+
+### Fixed
+- Fixed audio capture on Windows
+- Fixed window selector thumbnail generation
+- Fixed crash when OpenAI connection drops
+
+## [0.2.0] - 2026-01-01
+
+### Added
+- **Window Selector**: Choose specific windows or screens to capture
+- **Manual Screenshot**: Hotkey to capture screenshots on demand
+- **Output Directory Setting**: Choose where sessions are saved
+- **Clipboard Integration**: Auto-copy summary to clipboard
+
+### Changed
+- Improved UI responsiveness
+- Better error messages
+
+### Fixed
+- Fixed hotkey conflicts with system shortcuts
+- Fixed screenshot resolution on Retina displays
+
+## [0.1.0] - 2025-12-15
+
+### Added
+- Initial release
+- Voice narration capture with OpenAI transcription
+- Automatic screenshot capture on voice pauses
+- Markdown document generation
+- Global hotkey to start/stop recording (`Cmd+Shift+F`)
+- System tray icon
+- Basic settings (API key configuration)
+
+---
+
+## Version History Summary
+
+| Version | Date | Highlights |
+|---------|------|------------|
+| 1.0.0 | 2026-02-04 | **Initial Public Release** - Bulletproof state machine, offline Whisper |
+| 0.4.0 | 2026-02-02 | Export formats, crash recovery, auto-updater |
+| 0.3.0 | 2026-01-15 | Transcription preview, intelligent capture, settings |
+| 0.2.0 | 2026-01-01 | Window selector, manual screenshots |
+| 0.1.0 | 2025-12-15 | Initial scaffold |
+
+[Unreleased]: https://github.com/eddiesanjuan/markupr/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/eddiesanjuan/markupr/compare/v0.4.0...v1.0.0
+[0.4.0]: https://github.com/eddiesanjuan/markupr/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/eddiesanjuan/markupr/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/eddiesanjuan/markupr/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/eddiesanjuan/markupr/releases/tag/v0.1.0

package/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md - markupr
+
+## Project Overview
+
+markupr is a macOS menu bar app that intelligently captures developer feedback. It records your screen and voice simultaneously, then uses an intelligent post-processing pipeline to correlate transcript timestamps with the screen recording — extracting the right frames at the right moments and stitching everything into a structured, AI-ready Markdown document. The output is purpose-built for AI coding agents: every screenshot placed exactly where it belongs, every issue clearly documented.
+
+**Version:** 1.2.0
+**License:** MIT (Open Source)
+
+## Tech Stack
+
+- **Framework:** Electron + React + TypeScript
+- **Build:** electron-vite + Vite
+- **Transcription:** Local Whisper (default), OpenAI Whisper-1 API (optional cloud)
+- **AI Analysis:** Anthropic Claude API (BYOK or premium tier)
+- **Testing:** Vitest (356 tests)
+- **Package:** electron-builder
+- **Styling:** Tailwind CSS
+
+## Architecture
+
+```
+src/
+├── main/                   # Electron main process
+│   ├── index.ts            # Entry point, window management, IPC orchestration
+│   ├── SessionController.ts # 7-state FSM with watchdog timer
+│   ├── CrashRecovery.ts    # Auto-save every 5s, crash detection, recovery dialog
+│   ├── ErrorHandler.ts     # Centralized error handling
+│   ├── HotkeyManager.ts    # Global hotkey registration
+│   ├── MenuManager.ts      # Application menu
+│   ├── TrayManager.ts      # Menu bar tray icon and status
+│   ├── PermissionManager.ts # macOS permission checks
+│   ├── AutoUpdater.ts      # Auto-update via electron-updater
+│   ├── ai/                 # AI analysis pipeline (Claude)
+│   │   ├── AIPipelineManager.ts  # Orchestrates AI analysis (free/byok/premium tiers)
+│   │   ├── ClaudeAnalyzer.ts     # Claude API integration
+│   │   ├── ImageOptimizer.ts     # Screenshot optimization for API
+│   │   ├── StructuredMarkdownBuilder.ts # AI-enhanced markdown output
+│   │   └── types.ts              # AI pipeline types
+│   ├── analysis/           # Feedback analysis and categorization
+│   ├── audio/              # Microphone capture, VAD
+│   ├── capture/            # Screen capture via desktopCapturer
+│   ├── output/             # Document generation and export
+│   │   ├── MarkdownGenerator.ts  # llms.txt-inspired markdown output
+│   │   ├── ExportService.ts      # Multi-format export (MD, PDF, HTML, JSON)
+│   │   ├── ClipboardService.ts   # Clipboard bridge (copies file path)
+│   │   ├── FileManager.ts        # Session file management
+│   │   └── sessionAdapter.ts     # Type conversion utilities
+│   ├── pipeline/           # Post-processing pipeline
+│   │   ├── PostProcessor.ts      # Pipeline orchestrator (transcribe → analyze → extract → generate)
+│   │   ├── TranscriptAnalyzer.ts # Heuristic key-moment detection
+│   │   └── FrameExtractor.ts     # ffmpeg-based video frame extraction
+│   ├── platform/           # Platform-specific code (Windows taskbar)
+│   ├── settings/           # Persistent settings with secure API key storage
+│   ├── transcription/      # Transcription tier management
+│   │   ├── TierManager.ts       # Tier selection (Whisper, timer-only)
+│   │   ├── WhisperService.ts     # Local Whisper integration
+│   │   └── ModelDownloadManager.ts # Whisper model download from HuggingFace
+│   └── windows/            # Window management (popover, taskbar)
+├── renderer/               # React UI
+│   ├── App.tsx             # Main component with state machine UI
+│   ├── AppWrapper.tsx      # Root wrapper with providers
+│   ├── components/         # UI components
+│   │   ├── AnnotationOverlay.tsx    # Drawing tools (arrow, circle, rect, freehand, text)
+│   │   ├── AudioWaveform.tsx        # Real-time audio level visualization
+│   │   ├── CrashRecoveryDialog.tsx  # Crash recovery UI
+│   │   ├── DonateButton.tsx         # Rotating donate messages
+│   │   ├── ModelDownloadDialog.tsx   # Whisper model download UI
+│   │   ├── Onboarding.tsx           # First-run experience
+│   │   ├── SessionHistory.tsx       # Session browser
+│   │   ├── SessionReview.tsx        # Post-recording review/edit
+│   │   ├── SettingsPanel.tsx        # Settings configuration
+│   │   └── ...                      # Other UI components
+│   ├── audio/              # Renderer-side audio capture bridge
+│   ├── capture/            # Renderer-side screen recording (MediaRecorder)
+│   └── hooks/              # React hooks (theme, animation)
+├── preload/                # Context bridge (secure IPC)
+└── shared/                 # Types shared between processes
+    ├── types.ts            # IPC channels, payload types, state types
+    └── hotkeys.ts          # Hotkey configuration types
+```
+
+## Commands
+
+```bash
+npm run dev          # Development mode with hot reload
+npm run build        # Build for production
+npm run build:desktop # Build desktop app only
+npm test             # Run all tests (356 tests)
+npm run test:unit    # Run unit tests only
+npm run test:watch   # Run tests in watch mode
+npm run lint         # Lint code
+npm run lint:fix     # Auto-fix lint issues
+npm run typecheck    # TypeScript check
+npm run package      # Package for current platform
+npm run package:mac  # Package for macOS
+npm run package:win  # Package for Windows
+```
+
+## Key Architecture Decisions
+
+### State Machine
+The recording session is governed by a 7-state FSM: `idle → starting → recording → stopping → processing → complete → error`. Every state has a maximum duration enforced by a watchdog timer that forces recovery if anything gets stuck.
+
+### Post-Processing Pipeline
+When recording stops, the pipeline runs: audio transcription (Whisper) → transcript analysis (key-moment detection) → video frame extraction (ffmpeg) → markdown generation. Each step degrades gracefully if a dependency is missing.
+
+### Three-Tier Transcription
+1. **OpenAI Whisper-1 API** (optional, best quality) — cloud-based, requires API key
+2. **Local Whisper** (default) — runs on device, no API key needed
+3. **Timer-only** (fallback) — captures screenshots on a timer when no transcription is available
+
+### Crash Recovery
+Session state auto-saves to disk every 5 seconds. On restart after a crash, the app detects the incomplete session and offers recovery.
+
+### Clipboard Bridge
+When a session completes, the **file path** to the markdown document is copied to clipboard — not the content. This is deliberate: the file persists on disk, and AI tools can read the full document including screenshots.
+
+## IPC Communication
+
+All main/renderer communication goes through the preload script. See `src/shared/types.ts` for IPC channel names.
+
+## Configuration
+
+No configuration required for first run. Local Whisper transcription works out of the box after downloading a model (~75MB for tiny, ~500MB for base).
+
+Optional API keys (stored securely in OS keychain):
+- **OpenAI** — for cloud post-session transcription
+- **Anthropic** — for AI-enhanced document analysis (BYOK mode)
+
+## Development Notes
+
+- Menu bar popover window, frameless, always-on-top
+- Screenshots saved as PNG files in session directories
+- Voice activity detection uses RMS amplitude analysis
+- All settings validated against JSON schema
+- Secure API key storage via keytar (macOS Keychain, Windows Credential Manager) with encrypted fallback

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,9 @@
+# Code of Conduct
+
+This project follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Enforcement
+
+Report violations to: **conduct@markupr.app**
+
+All reports will be reviewed and investigated promptly.

package/CONTRIBUTING.md

@@ -0,0 +1,390 @@
+# Contributing to markupr
+
+Thank you for your interest in contributing to markupr! This document provides guidelines and information about contributing.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [Getting Started](#getting-started)
+- [How to Contribute](#how-to-contribute)
+- [Development Workflow](#development-workflow)
+- [Pull Request Process](#pull-request-process)
+- [Style Guide](#style-guide)
+- [Reporting Issues](#reporting-issues)
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and inclusive environment. Please:
+
+- Be respectful and considerate in all interactions
+- Welcome newcomers and help them learn
+- Focus on constructive feedback
+- Accept responsibility for mistakes and learn from them
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+- Git
+- A code editor (VS Code recommended)
+
+### Setup
+
+1. **Fork the repository** on GitHub
+
+2. **Clone your fork**:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/markupr.git
+   cd markupr
+   ```
+
+3. **Add upstream remote**:
+   ```bash
+   git remote add upstream https://github.com/eddiesanjuan/markupr.git
+   ```
+
+4. **Install dependencies**:
+   ```bash
+   npm install
+   # or
+   bun install
+   ```
+
+5. **Start development**:
+   ```bash
+   npm run dev
+   # or
+   bun run dev
+   ```
+
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development instructions.
+
+## How to Contribute
+
+### Types of Contributions
+
+We welcome many types of contributions:
+
+- **Bug fixes**: Fix issues in existing code
+- **Features**: Add new functionality
+- **Documentation**: Improve or add documentation
+- **Tests**: Add or improve test coverage
+- **Performance**: Optimize existing code
+- **Accessibility**: Improve accessibility
+- **Translations**: Help translate the UI
+
+### Finding Issues to Work On
+
+- Check [issues labeled "good first issue"](https://github.com/eddiesanjuan/markupr/labels/good%20first%20issue) for beginner-friendly tasks
+- Check [issues labeled "help wanted"](https://github.com/eddiesanjuan/markupr/labels/help%20wanted) for tasks where we need help
+- Feel free to propose your own ideas by opening an issue first
+
+### Before Starting Work
+
+1. **Check existing issues** to avoid duplicate work
+2. **Comment on the issue** to let others know you're working on it
+3. **For significant changes**, open an issue first to discuss the approach
+4. **For new features**, wait for approval before starting implementation
+
+## Development Workflow
+
+### Branch Naming
+
+Use descriptive branch names:
+
+- `feature/add-pdf-export`
+- `fix/hotkey-conflict`
+- `docs/update-readme`
+- `refactor/settings-panel`
+
+### Making Changes
+
+1. **Create a branch**:
+   ```bash
+   git checkout -b feature/my-feature
+   ```
+
+2. **Make your changes**:
+   - Follow the [style guide](#style-guide)
+   - Keep commits focused and atomic
+   - Write clear commit messages
+
+3. **Test your changes**:
+   ```bash
+   npm test
+   npm run lint
+   npm run typecheck
+   # bun equivalents:
+   # bun run test
+   # bun run lint
+   # bun run typecheck
+   ```
+
+4. **Update documentation** if needed
+
+5. **Commit your changes**:
+   ```bash
+   git commit -m "feat: add new export format"
+   ```
+
+### Commit Message Format
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types**:
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Code style (formatting, etc.)
+- `refactor`: Code change that neither fixes nor adds
+- `perf`: Performance improvement
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+**Examples**:
+```
+feat(export): add PDF export format
+fix(hotkey): resolve conflict with system shortcuts
+docs(readme): update installation instructions
+refactor(settings): simplify settings manager
+```
+
+### Keeping Your Fork Updated
+
+```bash
+git fetch upstream
+git checkout main
+git merge upstream/main
+git push origin main
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+Ensure your PR:
+
+1. **Follows the style guide**
+2. **Passes all tests**: `npm test`
+3. **Passes linting**: `npm run lint`
+4. **Passes type checking**: `npm run typecheck`
+5. **Has been tested manually**
+6. **Includes documentation updates** (if applicable)
+7. **Has a clear description**
+
+### Submitting a PR
+
+1. **Push your branch**:
+   ```bash
+   git push origin feature/my-feature
+   ```
+
+2. **Open a Pull Request** on GitHub
+
+3. **Fill out the PR template**:
+   - Describe what the PR does
+   - Link related issues
+   - List any breaking changes
+   - Include screenshots for UI changes
+
+4. **Request review** if not automatically assigned
+
+### PR Template
+
+```markdown
+## Description
+Brief description of changes.
+
+## Related Issues
+Fixes #123
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation
+- [ ] Refactoring
+- [ ] Other (describe)
+
+## Testing
+Describe how you tested the changes.
+
+## Screenshots
+(If applicable)
+
+## Checklist
+- [ ] Tests pass (`npm test`)
+- [ ] Lint passes (`npm run lint`)
+- [ ] Types check (`npm run typecheck`)
+- [ ] Documentation updated
+- [ ] Manually tested
+```
+
+### Review Process
+
+1. **Automated checks** must pass
+2. **At least one maintainer** must approve
+3. **All comments** must be resolved
+4. **No merge conflicts** with main
+
+### After Merging
+
+- Delete your branch
+- Pull changes to your local main
+- Celebrate your contribution! 🎉
+
+## Style Guide
+
+### TypeScript
+
+```typescript
+// Use explicit types
+function createSession(sourceId: string): Session {
+  // ...
+}
+
+// Use interfaces for objects
+interface SessionOptions {
+  sourceId: string;
+  sourceName?: string;
+}
+
+// Use const assertions for literals
+const STATUS = {
+  IDLE: 'idle',
+  RECORDING: 'recording',
+} as const;
+```
+
+### React
+
+```tsx
+// Use functional components
+export function SessionStatus({ state }: SessionStatusProps) {
+  const [isActive, setIsActive] = useState(false);
+
+  useEffect(() => {
+    // Cleanup subscriptions
+    return () => cleanup();
+  }, []);
+
+  return <div className="status">{state}</div>;
+}
+
+// Prefer named exports
+export { SessionStatus };
+```
+
+### CSS / Tailwind
+
+```tsx
+// Use Tailwind utilities
+<div className="bg-gray-900 text-white p-4 rounded-lg shadow-md">
+
+// For complex styles, use cn() helper
+<div className={cn(
+  "base-styles",
+  isActive && "active-styles",
+  className
+)}>
+```
+
+### File Organization
+
+```
+src/
+├── main/
+│   ├── services/      # Service classes
+│   ├── utils/         # Utility functions
+│   └── types/         # Main-specific types
+├── renderer/
+│   ├── components/    # React components
+│   ├── hooks/         # Custom hooks
+│   └── utils/         # Utility functions
+└── shared/
+    └── types.ts       # Shared types
+```
+
+### Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Components | PascalCase | `SessionReview.tsx` |
+| Hooks | camelCase, `use` prefix | `useSessionState.ts` |
+| Utilities | camelCase | `formatTime.ts` |
+| Types | PascalCase | `SessionState` |
+| Constants | UPPER_SNAKE_CASE | `MAX_RETRIES` |
+
+## Reporting Issues
+
+### Before Reporting
+
+1. **Check existing issues** for duplicates
+2. **Try latest version** - issue may be fixed
+3. **Collect information**:
+   - OS and version
+   - markupr version
+   - Steps to reproduce
+   - Error messages/logs
+
+### Bug Report Template
+
+```markdown
+## Description
+Clear description of the bug.
+
+## Steps to Reproduce
+1. Go to '...'
+2. Click on '...'
+3. See error
+
+## Expected Behavior
+What should happen.
+
+## Actual Behavior
+What actually happens.
+
+## Environment
+- OS: macOS 14.0
+- markupr: 0.4.0
+- Node: 18.19.0
+
+## Screenshots/Logs
+(If applicable)
+
+## Additional Context
+Any other relevant information.
+```
+
+### Feature Request Template
+
+```markdown
+## Problem
+Describe the problem this feature would solve.
+
+## Proposed Solution
+How you envision the feature working.
+
+## Alternatives Considered
+Other approaches you've thought about.
+
+## Additional Context
+Mockups, examples, or references.
+```
+
+## Questions?
+
+- Open a [discussion](https://github.com/eddiesanjuan/markupr/discussions)
+- Check [documentation](docs/)
+- Review existing [issues](https://github.com/eddiesanjuan/markupr/issues)
+
+Thank you for contributing to markupr!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eddie San Juan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.