SnapSparrow · Implementation Plan

Image import, alongside pasted screenshots

Date 11 September 2026 Task A45EB9D2 Branch main New files 2 Status implemented, builds clean

Decisions locked

What already exists

Every image reaching the app today comes from the clipboard. There is no file import, no drag-and-drop of external images, and no screen-capture API usage anywhere — the app relies on macOS's own ⌘⇧4 and then reads the pasteboard. Two near-identical routines do the ingesting:

Routine	Behavior	Reached from
AppDelegate.addImageFromData SnapSparrowApp.swift:488	Appends to the active grid, marks stripState.newImageIds, records .addImage, saves immediately	⌥⇧S, ⌥⇧4, strip Paste button, status menu, ClipboardMonitor auto-add
FlowSceneView.pasteImageFromClipboard FlowSceneView.swift:1722	Inserts at activeIndex + 1, caches the bitmap, animates to the new slide	⌘V while the compose window is focused

Both normalize to PNG and write into sessions/{docId}/. ClipboardService.readImage() already accepts image file URLs off the pasteboard, so the decode-and-normalize logic import needs exists already — it is just private and clipboard-bound.

The app is LSUIElement: true with no SwiftUI menu bar and no WindowGroup; its only scene is Settings. There is no Commands block to hang ⌘O on, so shortcuts live either in AppDelegate.installKeyboardMonitor() or as .onKeyPress in the focused view.

Plan

1Extract the shared decode path

new — SnapSparrow/Services/ImageNormalization.swift

ClipboardService keeps imageSize(from:) and convertToPNG(_:) private. Import needs the same two steps, so lift them into one enum rather than copying them:

enum ImageNormalization {
    /// Decodes `data`, returning PNG-normalized bytes and pixel dimensions.
    /// Returns nil when the bytes are not a decodable bitmap.
    static func normalizedPNG(from data: Data) -> (data: Data, size: CGSize)?
}

Rewrite ClipboardService.readImage's three call sites to use it. Behavior is identical — the convertToPNG(data) ?? data fallback moves inside normalizedPNG unchanged.

2The import service

new — SnapSparrow/Services/ImageImportService.swift

enum ImageImportService {
    /// The one place accepted types are declared.
    static let acceptedTypes: [UTType] = [.png, .jpeg]
    static let acceptedExtensions: Set<String> = ["png", "jpg", "jpeg"]

    struct Loaded { let data: Data; let size: CGSize; let sourceName: String }
    struct Outcome { let loaded: [Loaded]; let failures: [String] }

    /// Modal NSOpenPanel, multi-select, files only. Returns [] on cancel.
    @MainActor static func chooseFiles() -> [URL]

    /// Reads and PNG-normalizes each URL **in the order given**. Unreadable
    /// files land in `failures` by name; the rest still import.
    static func load(urls: [URL]) -> Outcome

    /// Filters NSItemProvider-resolved URLs to accepted extensions.
    static func acceptable(_ urls: [URL]) -> [URL]
}

The panel sets allowsMultipleSelection = true, canChooseDirectories = false, prompt = "Import". Because the app is LSUIElement, raising the panel from the status menu with no key window needs NSApp.activate(ignoringOtherApps: true) first.

3Batch undo

AnnotationUndoManager.swift

A six-file import has to undo in one ⌘Z, not six. Two new mutually-inverse cases beside the existing .addImage / .removeAddedImage pair:

case addImages([CapturedImage])
case removeAddedImages([CapturedImage])

.addImages appends each in array order, matching Grid.addImage, which rewrites order to images.count. .removeAddedImages removes each by id. Single-file imports use the same case with a one-element array, so there is no special path.

4Append-path import

SnapSparrowApp.swift

• addImagesFromData(_:) — the body of addImageFromData without the per-image undo record, then one .addImages and one saveImmediately. addImageFromData is refactored to call it with a single element, so there is one implementation rather than a fourth copy of the six-step sequence.
• handleImport() — picker → load → add → toast "Imported 4 images", or "Imported 3 of 4 — couldn't read logo.png". Cancelling is a silent no-op.
• ⌘O in installKeyboardMonitor() beside the existing ⌘V branch, with the same responder is NSTextView bail-out.
• Status menu item "Import Images…" after "Paste from Clipboard". Menu targets are auto-assigned, so the new selector needs no extra wiring.

5Compose-window import and the drop target

FlowSceneView.swift

• importImages(urls:) — inserts sequentially from activeIndex + 1, mirroring pasteImageFromClipboard, caches each bitmap into imageCache, records one .addImages, animates to the first new slide.
• .onDrop(of: [.fileURL], isTargeted:) on the root VStack. Drop order is preserved by resolving providers into an index-keyed array and awaiting them as a group before any insertion. The deleted CaptureModalView.handleDrop interleaved DispatchQueue.main.async completions and lost order; this does not repeat that.
• While targeted: a 2pt coral inset border and a centered "Drop images to import" pill.
• No .onKeyPress for ⌘O here — the AppDelegate monitor already fires for this window, and a second handler would open two panels.

6Toolbar button — dropped

7Empty-state copy

FlowSceneView.swift:433

"Capture screenshots to get started" becomes "Paste a screenshot, drop an image, or press ⌘O to import". The current copy misdescribes what the app can do. This is labeling only — the canvas-level onDrop from step 5 already covers this region.

8Build step — hand-edit the pbxproj, do not run xcodegen

So the two new files get added to project.pbxproj by hand — a PBXFileReference and PBXBuildFile each, an entry in the Services group, and an entry in the target's PBXSourcesBuildPhase. Then xcodebuild -scheme SnapSparrow -configuration Debug build to verify.

Reconciling project.yml is worth doing and is not part of this task. It is a live trap for anyone who runs xcodegen expecting it to work.

Final review

Edge cases this plan does not solve

• JPEG to PNG inflation. A 200KB photographic JPEG becomes several MB of PNG in the session directory. Already true for JPEG paste; import makes it easy to do twenty at once, so session directories will grow faster than they do today.
• Redo after an inserted import appends. Inherited from .addImage — drop, undo, redo moves the images to the end of the grid. Fixing it means teaching five existing undo cases to carry insertion indices.
• No dedupe. Only ClipboardMonitor hashes content; manual paste has never deduped, and import will not either. Importing the same file twice writes two copies.
• No progress UI. Forty large files block the main thread inside load(urls:) for perceptible time. Under ten files this is imperceptible; I am not adding async progress until it matters.
• No size cap. There is no downscale or pixel budget on ingest today, and this adds none. A 10,000px-wide import is stored at full size.
• Nested drop targets. A file dropped on the filmstrip falls through to the canvas handler, since the filmstrip only accepts .text. Position within the filmstrip is ignored.
• Folders are skipped, not walked. Aliases and symlinks resolve and work; a dropped folder of images is filtered out by extension and reported as skipped.

Follow-ups left on the table

1. The strip toolbar could carry the picker beside its Paste button. The strip is the surface where images get gathered. Out of scope as specified, easy to add.
2. HEIC and TIFF — one line in acceptedTypes plus one in acceptedExtensions.
3. Reconcile project.yml so xcodegen is usable again, or delete it so nobody trusts it.
4. A compound undo case carrying insertion indices, which would fix redo-after-insert for .addImage and .addImages together.