konverter/AGENTS.md

AGENTS.md

Working notes for Konverter — a menu bar file converter for macOS, written in Swift with SwiftPM and no external dependencies. Read this before changing the drag machinery or the conversion catalog.

Commands

swift build                                   # debug
swift build -c release
./.build/debug/Konverter --self-test          # 46 checks, exits non-zero on failure
./.build/debug/Konverter --convert <files…> --to <ext>
./.build/debug/Konverter --convert <file> --tool <toolID> --param k=v
./build-app.sh <version>                      # → Konverter.app (signed)
./release.sh <version>                        # notarize + staple + zip + sha256
open Konverter.app

--self-test and --convert are handled in AppDelegate.applicationDidFinishLaunching before any UI is installed, so they work headlessly and never steal focus. The self-test writes its fixtures into a temp directory and cleans up. A SKIP line means an optional engine (ffmpeg / LibreOffice / cwebp) is absent, not a bug; a FAIL line is a bug.

Keep the self-test green and add a check whenever you add a converter or a tool — it is the only automated coverage in the repo.

Layout

Sources/Konverter/
  App.swift             @main, AppDelegate, monitor wiring, Services handler
  CLI.swift             --convert mode
  SelfTest.swift        the verification suite
  Core/
    Format.swift        Format, FileCategory, FileKind, ConversionCatalog
    Tools.swift         ToolID, ToolField, ToolParams, Timecode
    Actions.swift       ActionID + FileActions (AirDrop, Float, Copy, …)
    Settings.swift      UserDefaults-backed preferences, LoginItem
    JobStore.swift      job queue, progress, reveal, notifications
    OutputNaming.swift  destination paths, conflict policy
    Shell.swift         Process wrapper, tool lookup
    Toolchain.swift     optional engine detection (ffmpeg, soffice, cwebp)
    WheelOption.swift   WheelItem/WheelKind and wheel construction
  Drag/
    DragMonitor.swift   global mouse monitors + drag pasteboard reading
    WheelController.swift overlay window, geometry, DropCatcher, commit
    WheelView.swift     SwiftUI radial wheel and list views
  Convert/
    Converter.swift     dispatch table + Availability rules
    ToolRunner.swift    every ToolID implementation
    ImageConverter.swift, ImageTools.swift
    PDFConverter.swift, DocumentConverter.swift, TextDocument.swift, Markdown.swift
    AVConverter.swift, MediaTools.swift, FFmpeg.swift
    ArchiveConverter.swift, SpreadsheetConverter.swift, EbookConverter.swift
    SubtitleConverter.swift, Office.swift
  UI/
    MenuBar.swift, QuickMenu.swift, PreferencesWindow.swift, OptionsWindow.swift
    ResultWindow.swift, JobPanel.swift, FloatPanel.swift, Notifier.swift

Converter.convert(source:to:at:) handles plain format changes; ToolRunner.run(tool:inputs:params:) handles transforms. Both funnel through Availability for the "is the engine present?" question, and both report errors as ConversionError (a LocalizedError) so the CLI and the UI show the same wording.

How the drag wheel works

This is the part with real constraints, so it is worth stating plainly.

1. Detecting the drag. DragMonitor installs global (and local) monitors for .leftMouseDragged etc. Mouse events need no permission. On the first drag event it reads NSPasteboard(name: .drag) for file URLs. If there are none, it is not a file drag and we ignore it.
2. Showing the overlay. WheelController.present creates a borderless OverlayWindow at .screenSaver - 1, non-key, ignoresMouseEvents = false, with a full-screen DropCatcher view. A 60 Hz timer polls NSEvent.mouseLocation and NSEvent.modifierFlags to decide which wheel to show and what is highlighted — because a non-key window cannot read modifier flags from the event stream.
3. Consuming the drop. DropCatcher is a real NSDraggingDestination. That is what stops Finder from moving the file: Finder hands the drop to us and considers the drag handled. Never replace this with a borderless window that merely looks like it is on top — Finder will happily move the file out from under you.
4. Ending. Drop → commitDrop() runs the job. Escape, dead-zone drop, or a mouse-up outside the wheel → cancel(), which hides the overlay and lets the drag continue wherever it landed.
5. Keys are optional. Escape/arrows/Return come from a global key monitor, which does require Accessibility. All of them are also reachable by pointer, so the app must never require that permission. Do not move essential behaviour into the key path.

Two ordering traps live here. NSEvent.modifierFlags is global state, not the event's flags — read it during the tick, not once at drag start. And the wheel geometry (WheelController.geometry/hit testing) is unit-tested by the "Wheel geometry" section of the self-test; if you change the radius or segment maths, update those expectations rather than deleting them.

Conversion gotchas

• WebP has no ImageIO encoder on macOS. WebPEncoder shells out to cwebp, falls back to an ffmpeg with libwebp, and marks the format unavailable otherwise. sips cannot write WebP — verified, do not try.
• SVG, PSD, RAW are often undecodable by ImageIO. Raster.firstImage falls back to qlmanage/Quick Look rasterisation.
• Lossless "compression" (PNG/BMP/TIFF) ignores ImageIO's quality property, so ImageTools.compress posterises instead. If you ever reach for pngquant, remember it is not a dependency and must stay optional.
• PPTX/EPUB/XLSX/DOCX/RTF are hand-written OOXML/EPUB/zip writers. They are deliberately minimal: enough structure for Word/Numbers/Preview to open them cleanly, no styling round-trip. LibreOffice is used when real layout fidelity matters (PAGES/KEY/NUMBERS/PPT/XLS).
• track.formatDescriptions is [Any] — you need as! CMFormatDescription (as? is rejected as always-succeeds). The load(.formatDescriptions) API would be nicer but is async and the media-info path is synchronous.
• Optional engines must always degrade, never crash: absence of ffmpeg or LibreOffice should surface as an unavailable wheel item with a reason, and Toolchain.missingToolAdvice supplies the brew install … line for the UI.
• Mixed selections must never produce an empty wheel. WheelBuilder falls back to ToolID.combineTools(for:) (Zip, Merge) whenever a drag has no single category, and appends Zip to every multi-file tools wheel. mergePDF converts non-PDF inputs through Converter.convert(_:to:.pdf) into a temp folder, so it accepts photos and documents, not just PDFs. If you add a tool that works across kinds, add it to combineTools and cover it in the self-test.

Reference material

Research on the apps this project is modelled on lives in an untracked .reference/ folder (.reference/.gitignore contains *, so nothing there is ever committed). Currently: tangerine.md (the closed-source app we clone), filee.md + a shallow clone of KnifeLemon/Filee (MIT, the open-source sibling), and README.md indexing them. Read filee.md before designing a feature that Filee already has — the "borrow next" list there is the roadmap.

Build/bundle notes

• The app is an LSUIElement menu bar app; the bundle is assembled by build-app.sh with a handwritten Info.plist. Do not try to generate it from Package.swift, and do not commit Konverter.app or dist/.
• CFBundleIdentifier is dev.tzgyn.konverter. AppDelegate.terminateOtherInstances() kills stale copies at launch so the monitors never double up.
• Settings (our class) collides with SwiftUI's Settings scene — the scene must be written SwiftUI.Settings { EmptyView() }.
• The Finder Quick Action is an NSServices entry calling convertFiles:userData:error: on the app delegate. It follows the same path as the menu bar item.
• SMAppService.mainApp powers "open at login".

Releasing

Notarization is mandatory: an unnotarized build is not a release. release.sh will not print a sha256 unless Apple accepted the submission, the ticket is stapled, and spctl -a -vv Konverter.app reports source=Notarized Developer ID. Never suggest xattr -dr com.apple.quarantine or brew install --cask --no-quarantine as a workaround — fix the signing problem.

Push main before tea releases create (the tag must point at shipped source), then bump Casks/konverter.rb in TZGyn/homebrew-tap with the new version and sha256, and print the upgrade script:

brew update
brew upgrade --cask konverter

Credentials: ~/.config/kapture/AuthKey_K5KXMMSB28.p8, key id K5KXMMSB28, issuer 3e25e5dc-8b75-453f-a71c-c7f3feaac628, team RX6767S6BW. Never commit the key.