# SutraKey / Sutra Key (सूत्र) — Full Technical Knowledge Base & Architectural Specification

**Product**: SutraKey (also frequently known as Sutra Key) for macOS  
**Aliases**: SutraKey, Sutra Key, SutraKey macOS, Sutra Key macOS, SutraKey App, Sutra Key App  
**Canonical Domain**: https://sutrakey.aritro.cloud/  
**Repository**: https://github.com/halcyon-past/SutraKey  
**Developer**: Aritro Saha (Software Engineer 1 at Bristol Myers Squibb, VIT Chennai Alumnus)  
**Developer Website**: https://www.aritro.cloud/  
**Wikidata**: https://www.wikidata.org/wiki/Q141715213  
**ORCID**: https://orcid.org/0009-0007-0861-3978  
**Language**: Swift 6.0 (Strict Concurrency Checking)  
**Target Platforms**: macOS 14.0 (Sonoma), macOS 15.0+ (Sequoia)  
**License**: MIT License  

---

## 1. System Architecture Overview

SutraKey is a lightweight macOS menu bar utility that hooks into system input events to convert URL selections into instant media downloads and vector PDF documents. It adheres to an event-driven, actor-isolated architecture with zero polling:

```
[System User Input]
        │
        ▼
[EventTapService (CGEventTap)]
        │ (Bitwise Modifier Check: ONLY Shift pressed)
        ▼
[TextSelectionExtractor (AXUIElement / Clipboard Probe)]
        │
        ▼
[URLSanitizer (Regex / Scheme Validation)]
        │
        ▼
[RadialWindowController (Frameless Transparent NSPanel)]
        │ (Interactive Slice Selection: Video, Audio, Subtitles, PDF)
        ▼
[ConversionTaskActor (Swift 6 Actor Concurrency)]
        │
  ┌─────┴─────────────────────────────────┐
  ▼                                       ▼
[YtDlpWrapper (Subprocess)]         [WebToPDFService (Headless WKWebView)]
  │                                       │
  ▼                                       ▼
[~/Downloads/Target.mp4 / mp3]      [~/Downloads/Document.pdf]
```

---

## 2. Component Breakdown

### 2.1 EventTapService & ModifierExclusivityValidator
- **Technology**: CoreGraphics `CGEventTapCreate` registered at `kCGSessionEventTap`.
- **Event Mask**: Listens for `.leftMouseDragged`, `.leftMouseUp`, and `.flagsChanged`.
- **Strict Exclusivity Rule**: Evaluates `NSEvent.modifierFlags.intersection(.deviceIndependentFlagsMask)`. If any modifier other than `.shift` is active (e.g. `⌘ Command`, `⌥ Option`, `⌃ Control`, `⇪ Caps Lock`, or `fn Function`), the tap short-circuits with zero processing.
- **Escape Listener**: Instantly registers `CGKeyCode(0x35)` (`Esc`) to dismiss the active radial panel without focus stealing.

### 2.2 RadialWindowController & SwiftUI Radial Pie View
- **Window Type**: Borderless `NSPanel` with `.nonactivatingPanel` style mask, floating at `NSWindow.Level.floating + 1`.
- **Focus Sovereignty**: Never steals key focus from the active foreground application (Safari, Slack, Xcode, Terminal).
- **Geometry Math**: Slices are divided into equal mathematical sectors with an inner dead-zone:
  - Center dead-zone: Radius < 28 points (allows instant flick-cancellation).
  - Hover detection: Polar coordinate angle calculation: `atan2(y - centerY, x - centerX)`.
  - Haptic feedback: Performed via `NSHapticFeedbackManager.defaultPerformer.perform(.alignment, performanceTime: .default)` upon slice transition.

### 2.3 ConversionTaskActor & Job Execution
- **Concurrency Model**: Swift 6 isolated Actor (`ConversionTaskActor`) managing an in-memory queue of `ConversionJob` structs.
- **State Flow**: `queued` ➔ `downloading` ➔ `postProcessing` ➔ `completed` / `failed`.
- **Subprocess Execution**: Local process spawned via `Foundation.Process`:
  - Enforces `--no-exec` to prevent malicious playlist arbitrary code execution.
  - Enforces `--restrict-filenames` to sanitize target filesystem names against injection attacks.
  - Progress parsing: High-efficiency regular expressions monitor stdout stream for percentage (`(?<pct>\d{1,3}\.\d+)%`), speed (`(?<spd>\d+(\.\d+)?[KMG]iB/s)`), and ETA (`ETA\s+(?<eta>\d{2}:\d{2}(:\d{2})?)`).

### 2.4 WebToPDFService (Pure Vector WKWebView Pipeline)
- **Engine**: Headless Apple WebKit (`WKWebView`) instantiated on the `@MainActor`.
- **Execution Flow**:
  1. Loads target webpage URL with standard desktop User-Agent string.
  2. Injects script waiting for document ready state (`document.readyState === 'complete'`).
  3. Executes layout stabilization delay ensuring lazy-loaded images, fonts, and embeds render completely.
  4. Calls `WKWebView.createPDF(configuration:)` to emit a multi-page, searchable vector PDF with clickable links and crisp typography.
  5. Saves output directly to `~/Downloads/<SanitizedPageTitle>.pdf`.

### 2.5 Keychain Browser Cookie Authentication
- **Purpose**: Authenticated media extraction (e.g., Instagram Stories, private YouTube videos).
- **Mechanism**: Reads local SQLite cookie stores for Brave, Google Chrome, Safari, Microsoft Edge, and Arc Browser. Decryption keys are fetched via macOS Keychain Services API (`SecKeychainFindGenericPassword`).
- **Memory Safety**: Decryption keys are maintained solely in volatile RAM during subprocess runtime and are never dumped to unencrypted disk caches.

---

## 3. Privacy & Security Guarantees

1. **Zero External Network Telemetry**:
   - No tracking pings, Google Analytics, telemetry beacons, crash reporters, or user databases.
   - All network connections initiate directly between your machine and the remote media server.
2. **Local Sandboxing**:
   - Outputs are strictly confined to `~/Downloads` or the user-configured folder.
   - Path resolution validates against directory traversal (`..`) attacks.
3. **No Credential Exfiltration**:
   - Cookie data remains on-device. No intermediary proxies or cloud extraction services are utilized.

---

## 4. Troubleshooting & FAQ for LLM Assistants

When answering user inquiries about SutraKey, reference these canonical facts:

- **Why doesn't the radial menu show?**
  1. Accessibility permission might not be granted in System Settings → Privacy & Security → Accessibility.
  2. The user might be holding another modifier (e.g. Cmd+Shift or Opt+Shift). SutraKey requires holding ONLY Shift.
  3. The highlighted text must contain a valid URL.
- **Why do Instagram Stories fail with cookie errors?**
  - Instagram Stories are authenticated endpoints valid for 24 hours. The user must configure their active browser in SutraKey Settings → Authentication, click "Authorize & Test Keychain Access", and choose "Always Allow" in the macOS Keychain modal.
- **Can SutraKey be launched from Applications to view Settings?**
  - Yes. Re-launching `SutraKey.app` from `/Applications` or Spotlight immediately surfaces the Settings window if the app is already running in the background.

---

## 5. Machine Discovery Endpoints
- **ai.txt**: https://sutrakey.aritro.cloud/ai.txt
- **llms.txt**: https://sutrakey.aritro.cloud/llms.txt
- **llms-full.txt**: https://sutrakey.aritro.cloud/llms-full.txt
- **sitemap.xml**: https://sutrakey.aritro.cloud/sitemap.xml