Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
237 changes: 149 additions & 88 deletions ARCHITECTURE.md

Large diffs are not rendered by default.

24 changes: 16 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,18 +34,24 @@

---

## Screenshots
## See it in action

<p align="center">
<img src="Resources/screens/classic_items.png" width="49%" alt="Classic Tab — Clipboard History & Previews" />
<img src="Resources/screens/media_items.png" width="49%" alt="Media Tab — Image History & Tags" />
<a href="Resources/reel/clap_reel.mp4">
<img src="Resources/reel/clap_reel_preview.webp" width="100%" alt="clap in 30 seconds — shortcut, search, OCR, smart cards, shell history, privacy">
</a>
</p>

<p align="center">
<img src="Resources/screens/shell_items.png" width="49%" alt="Shell Tab — Shell Command History" />
<img src="Resources/screens/settings.png" width="49%" alt="Settings Window — Limits & Customization" />
<img src="Resources/screens/classic_items.png" width="49%" alt="Classic tab — clipboard history with pins, favorites, tags and a JSON preview" />
<img src="Resources/screens/media_items.png" width="49%" alt="Media tab — image grid with OCR text extracted from a screenshot" />
</p>

<p align="center">
<img src="Resources/screens/features_overview.png" width="98%" alt="Settings with live usage and health checks; the Favs pinboard in front of the Shell tab; smart cards for JWT, epoch timestamps, colors and JSON repair" />
</p>


---

## Installation
Expand Down Expand Up @@ -93,7 +99,7 @@ For development & testing:

```bash
swift build # Build ClapApp + clap CLI
swift test # Run 92 unit tests
swift test # Run the test suites (core, CLI, app)
.build/debug/ClapApp # Run debug app directly
```

Expand Down Expand Up @@ -130,7 +136,7 @@ Press **⌘⇧V** to open the panel (configurable in Settings to `⌘⇧B`, `⌘

```bash
clap # Open clipboard UI
clap list [--images] [--shell] [--limit N] # List recent clipboard or shell entries
clap list [--images|--shell] [--favorites] # List recent entries (also --tag, --limit, --json)
clap search <query> [--type text|image|shell] # Full-text search
clap search --regex "^docker.*" # Regex search
clap get <id> # Show entry (pipe-friendly raw output)
Expand All @@ -139,8 +145,10 @@ clap add <text> | - # Insert an entry (alias: clap
echo "piped" | clap add - # Insert from a pipe
clap delete <id> | --text <str> | --regex <pat> # Delete entries (alias: clap out)
clap pin <id> / clap unpin <id> # Pin/unpin entries
clap fav <id> / clap unfav <id> # Favorite/unfavorite entries
clap tag add|remove <id> <tag> / clap tags # Tags & pinboards
clap backup <dir> / clap restore <dir> # Full-history backup & restore
clap clear [--force] # Wipe history (preserves pinned)
clap clear [--force] # Wipe ALL history, pinned and favorites included
clap stats [--json] # Storage and activity metrics
clap config get [key] / set <key> <val> # Manage limits, retention, exclusions
clap doctor # System diagnostic checks
Expand Down
Binary file added Resources/reel/clap_reel.mp4
Binary file not shown.
Binary file added Resources/reel/clap_reel_preview.webp
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Resources/screens/classic_items.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added Resources/screens/features_overview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Resources/screens/media_items.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed Resources/screens/settings.png
Binary file not shown.
Binary file removed Resources/screens/shell_items.png
Binary file not shown.
42 changes: 36 additions & 6 deletions Sources/ClapApp/AppDelegate.swift
Original file line number Diff line number Diff line change
Expand Up @@ -124,17 +124,47 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
// rendering of clipboard history.
#if DEBUG
if let snapshotDir = ProcessInfo.processInfo.environment["CLAP_DEBUG_SNAPSHOT_DIR"] {
// Scriptable for README screenshots (all optional):
// CLAP_DEBUG_SNAPSHOT_TAB classic|shell|favs|media
// CLAP_DEBUG_SNAPSHOT_TAG pinboard tag for the Favs tab
// CLAP_DEBUG_SNAPSHOT_QUERY search text to type
// CLAP_DEBUG_SNAPSHOT_SELECT_ID entry id to select (default: row one)
// CLAP_DEBUG_SNAPSHOT_SETTINGS "1" = open the Settings window instead
let env = ProcessInfo.processInfo.environment
DispatchQueue.main.asyncAfter(deadline: .now() + 1.5) { [weak self] in
guard let self else { return }
if env["CLAP_DEBUG_SNAPSHOT_SETTINGS"] == "1" {
self.settingsController.show()
return
}
self.panelController.show()
if ProcessInfo.processInfo.environment["CLAP_DEBUG_SNAPSHOT_TAB"] == "media" {
self.appState.selectTab(.media)
switch env["CLAP_DEBUG_SNAPSHOT_TAB"] {
case "media": self.appState.selectTab(.media)
case "shell": self.appState.selectTab(.shell)
case "favs": self.appState.selectTab(.favs)
default: break
}
// Select the first row so the preview window appears too.
DispatchQueue.main.asyncAfter(deadline: .now() + 0.7) {
self.appState.moveSelection(1)
if let tag = env["CLAP_DEBUG_SNAPSHOT_TAG"] { self.appState.selectTag(tag) }
if let query = env["CLAP_DEBUG_SNAPSHOT_QUERY"] { self.appState.queryChanged(query) }
if let raw = env["CLAP_DEBUG_SNAPSHOT_SELECT_ID"], let id = Int64(raw) {
// Wait until the entry is actually loaded: selecting before
// the reload lands gets overwritten by its row-one default.
Task { @MainActor in
for _ in 0..<30 where !self.appState.flatRows.contains(where: { $0.id == id }) {
try? await Task.sleep(nanoseconds: 100_000_000)
}
try? await Task.sleep(nanoseconds: 200_000_000)
self.appState.selectedID = id
}
} else {
DispatchQueue.main.asyncAfter(deadline: .now() + 0.7) {
// The reload usually auto-selects row one already.
if self.appState.selectedID == nil { self.appState.moveSelection(1) }
}
}
DispatchQueue.main.asyncAfter(deadline: .now() + 2.0) {
// Selection at +0.7s, preview auto-opens 1s later and animates
// for 0.28s — snapshot well after it has settled.
DispatchQueue.main.asyncAfter(deadline: .now() + 3.0) {
let dir = URL(fileURLWithPath: snapshotDir, isDirectory: true)
self.panelController.writeSnapshot(to: dir.appendingPathComponent("panel.png"))
}
Expand Down
21 changes: 19 additions & 2 deletions Sources/ClapApp/EdgeResizeOverlay.swift
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,28 @@ enum ResizeDirection {
case topLeft, topRight, bottomLeft, bottomRight

var cursor: NSCursor {
if #available(macOS 15.0, *) {
return .frameResize(position: frameResizePosition, directions: .all)
}
switch self {
case .left, .right: return .resizeLeftRight
case .top, .bottom: return .resizeUpDown
case .topLeft, .bottomRight: return .closedHand
case .topRight, .bottomLeft: return .closedHand
// No public diagonal resize cursor before macOS 15.
case .topLeft, .topRight, .bottomLeft, .bottomRight: return .crosshair
}
}

@available(macOS 15.0, *)
private var frameResizePosition: NSCursor.FrameResizePosition {
switch self {
case .left: return .left
case .right: return .right
case .top: return .top
case .bottom: return .bottom
case .topLeft: return .topLeft
case .topRight: return .topRight
case .bottomLeft: return .bottomLeft
case .bottomRight: return .bottomRight
}
}
}
Expand Down
2 changes: 1 addition & 1 deletion Sources/ClapApp/MenuBar.swift
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ final class MenuBarController: NSObject, NSMenuDelegate {
guard let self else { return }
let recent = (try? await self.store.list(type: .text, limit: 5, offset: 0)) ?? []
let paused = ((try? await self.store.config(ConfigKey.monitoringPaused)) ?? "0") == "1"
let hotkeyStr = ((try? await self.store.config("ui.hotkey")) ?? "cmd+shift+v")
let hotkeyStr = ((try? await self.store.config(ConfigKey.uiHotkey)) ?? HotKeyDefinition.defaultID)
self.currentShortcut = HotKeyDefinition.find(hotkeyStr)
self.cachedRecent = recent
self.cachedPaused = paused
Expand Down
92 changes: 64 additions & 28 deletions Sources/ClapApp/Panel.swift
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,13 @@ final class ClapPanel: NSPanel {
override var canBecomeKey: Bool { true }
override var canBecomeMain: Bool { false }

/// Set by PanelController so every close path collapses the preview and
/// records the frame, rather than a bare orderOut leaving it widened.
var onCancel: (() -> Void)?

/// Esc via the responder chain.
override func cancelOperation(_ sender: Any?) {
orderOut(nil)
if let onCancel { onCancel() } else { orderOut(nil) }
}
}

Expand Down Expand Up @@ -65,6 +69,7 @@ final class PanelController: NSObject, NSWindowDelegate {
panel.delegate = self
panel.contentView = NSHostingView(rootView: ContentView().environmentObject(appState))

panel.onCancel = { [weak self] in self?.hide() }
installKeyMonitor()

appState.slideout.window = panel
Expand All @@ -91,8 +96,9 @@ final class PanelController: NSObject, NSWindowDelegate {
Task { [weak self] in
guard let raw = try? await appState.store.config(Self.frameConfigKey) else { return }
let rect = NSRectFromString(raw)
guard let self, self.savedFrame == nil else { return }
if rect.width >= Self.minPanelSize.width, rect.height >= Self.minPanelSize.height {
self?.savedFrame = rect
self.savedFrame = rect
}
}
}
Expand All @@ -117,26 +123,32 @@ final class PanelController: NSObject, NSWindowDelegate {
front.bundleIdentifier != Bundle.main.bundleIdentifier {
previousApp = front
}
appState.panelWillShow()
appState.panelWillShow() // collapses any open preview first
suppressFrameSave = true
var targetSize = savedFrame?.size ?? Self.panelSize
targetSize.width = appState.slideout.contentWidth

if let saved = savedFrame, frameIsOnAVisibleScreen(saved) {
// Reopen exactly where the user last dragged/resized it.
var reopenFrame = saved
reopenFrame.size.width = targetSize.width
panel.setFrame(reopenFrame, display: false)
let slideout = appState.slideout
if let saved = savedFrame {
// The saved frame is the source of truth for the list width;
// contentWidth starts at a default every launch.
slideout.contentWidth = max(slideout.minimumContentWidth, saved.width)
}
let targetSize = NSSize(width: slideout.contentWidth,
height: savedFrame?.height ?? Self.panelSize.height)

if let saved = savedFrame, let screen = Self.bestScreen(for: saved) {
// Reopen where the user left it, nudged fully on-screen (a display
// may have been rearranged or unplugged since).
let reopen = NSRect(origin: saved.origin, size: targetSize)
panel.setFrame(Self.clamp(reopen, to: screen.visibleFrame), display: false)
} else if let screen = screenWithMouse() {
let frame = screen.visibleFrame
let origin = NSPoint(
x: frame.midX - targetSize.width / 2,
y: frame.midY - targetSize.height / 2
)
panel.setFrame(NSRect(origin: origin, size: targetSize), display: false)
panel.setFrame(Self.clamp(NSRect(origin: origin, size: targetSize), to: frame),
display: false)
}
suppressFrameSave = false
appState.slideout.closePreview(animated: false)
if appState.selectedEntry != nil {
appState.slideout.startAutoOpen()
}
Expand Down Expand Up @@ -177,21 +189,40 @@ final class PanelController: NSObject, NSWindowDelegate {
return NSScreen.screens.first { NSMouseInRect(mouse, $0.frame, false) } ?? NSScreen.main
}

/// A frame counts as restorable when a meaningful part of it is on some
/// screen (the saved display may have been unplugged).
private func frameIsOnAVisibleScreen(_ frame: NSRect) -> Bool {
NSScreen.screens.contains { screen in
let visible = screen.visibleFrame.intersection(frame)
return visible.width >= 100 && visible.height >= 100
/// The screen showing the largest part of `frame`, or nil when it is on
/// none of them (display unplugged) — the caller then re-centers.
static func bestScreen(for frame: NSRect) -> NSScreen? {
var best: NSScreen?
var bestArea: CGFloat = 0
for screen in NSScreen.screens {
let overlap = screen.visibleFrame.intersection(frame)
guard !overlap.isNull else { continue }
let area = overlap.width * overlap.height
if area > bestArea {
best = screen
bestArea = area
}
}
return best
}

/// Shrinks `frame` to fit `bounds` if needed, then slides it inside.
static func clamp(_ frame: NSRect, to bounds: NSRect) -> NSRect {
var result = frame
result.size.width = min(result.width, bounds.width)
result.size.height = min(result.height, bounds.height)
result.origin.x = min(max(result.minX, bounds.minX), bounds.maxX - result.width)
result.origin.y = min(max(result.minY, bounds.minY), bounds.maxY - result.height)
return result
}

private func rememberCurrentFrame() {
guard !suppressFrameSave, panel.isVisible else { return }
var frame = panel.frame
if appState.slideout.state.isOpen {
frame.size.width = appState.slideout.contentWidth
}
let slideout = appState.slideout
// Preview open/close animations move and resize the window without
// the user doing anything; those intermediate frames must not be
// saved. The list itself doesn't move during them.
guard !suppressFrameSave, panel.isVisible, !slideout.state.isAnimating else { return }
let frame = slideout.listFrame(of: panel)
savedFrame = frame
// Debounced: windowDidMove fires continuously while dragging.
frameSaveTask?.cancel()
Expand All @@ -216,10 +247,15 @@ final class PanelController: NSObject, NSWindowDelegate {
func windowDidResize(_ notification: Notification) {
// Live-sync while dragging an edge with the preview open; the list
// absorbs the delta and the pane keeps its width.
guard appState.slideout.state == .open else { return }
appState.slideout.contentWidth = max(
appState.slideout.minimumContentWidth,
panel.frame.width - appState.slideout.slideoutWidth)
if appState.slideout.state == .open {
appState.slideout.contentWidth = max(
appState.slideout.minimumContentWidth,
panel.frame.width - appState.slideout.slideoutWidth)
}
// The edge-resize handles call setFrame directly, which never ends a
// "live resize", and top/right drags don't move the origin — so
// windowDidMove alone would miss them. Saves are debounced.
rememberCurrentFrame()
}

func windowDidEndLiveResize(_ notification: Notification) {
Expand Down
15 changes: 14 additions & 1 deletion Sources/ClapApp/PreviewCards.swift
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@
Text("JWT Inspector")
.font(.system(size: 12.5, weight: .bold))
.foregroundStyle(.primary)
.fixedSize()

Text(jwt.algorithm)
.font(.system(size: 10, weight: .semibold, design: .monospaced))
Expand All @@ -132,6 +133,7 @@
Capsule()
.fill(Color.primary.opacity(0.08))
)
.fixedSize()

if let isExp = jwt.isExpired {
HStack(spacing: 3) {
Expand All @@ -148,6 +150,7 @@
Capsule()
.fill((isExp ? Color.red : Color.green).opacity(0.12))
)
.fixedSize()
}

Spacer()
Expand All @@ -158,9 +161,14 @@
} label: {
Label("Copy JSON", systemImage: "doc.on.doc")
.font(.system(size: 10))
// Icon-only: title + both badges + a text label don't
// fit the minimum pane width without truncation.
.labelStyle(.iconOnly)
}
.buttonStyle(.bordered)
.controlSize(.mini)
.fixedSize()
.help("Copy payload or header JSON")
}

if jwt.subject != nil || jwt.issuer != nil || jwt.expirationDate != nil {
Expand Down Expand Up @@ -191,7 +199,12 @@

Text(jwt.payloadJSON)
.font(.system(size: 11, design: .monospaced))
.textSelection(.enabled)
// No .textSelection here: on macOS a selectable multi-line
// Text in this card collapses to its first line ("{…").
// "Copy JSON" covers copying. Capped so huge tokens can't
// swallow the pane.
.lineLimit(10)
.fixedSize(horizontal: false, vertical: true)
.padding(8)
.frame(maxWidth: .infinity, alignment: .leading)
.background(
Expand Down Expand Up @@ -337,7 +350,7 @@
if let image {
Image(nsImage: image)
.resizable()
.aspectRatio(contentMode: .fit)

Check warning on line 353 in Sources/ClapApp/PreviewCards.swift

View workflow job for this annotation

GitHub Actions / Build, Test & Lint (macOS)

Prefer `scaledToFit()` or `scaledToFill()` over `aspectRatio(contentMode:)` with a constant content mode (legacy_swiftui_aspect_ratio)

Check warning on line 353 in Sources/ClapApp/PreviewCards.swift

View workflow job for this annotation

GitHub Actions / Build, Test & Lint (macOS)

Prefer `scaledToFit()` or `scaledToFill()` over `aspectRatio(contentMode:)` with a constant content mode (legacy_swiftui_aspect_ratio)
.clipShape(RoundedRectangle(cornerRadius: 6, style: .continuous))
.overlay(
RoundedRectangle(cornerRadius: 6, style: .continuous)
Expand Down
Loading
Loading