delivery.md

앱 자동 전달 정책

목표

MVP의 자동 전달은 모든 앱에 대한 완전한 네이티브 연동이 아니라, 캡처 이미지를 클립보드에 복사한 뒤 대상 앱에 붙여넣기 이벤트를 보내는 방식으로 구현한다.

기본 방식

자동 전달 순서:

1. 캡처 이미지를 NSPasteboard에 복사한다.
2. 설정이 저장 및 전달이면 캡처 이미지를 저장한다.
3. 설정의 전달 대상 방식에 따라 대상을 결정한다.
4. 매번 앱 선택이면 실행 중인 앱 목록과 윈도우 목록을 보여주고 사용자가 대상을 선택한다.
5. 가장 최근 사용 앱이면 캡처 시작 직전에 활성화되어 있던 앱을 대상으로 사용한다.
6. 지정한 앱이면 설정에 저장된 앱을 대상으로 사용한다.
7. Trace가 대상 앱 또는 선택한 윈도우를 활성화한다.
8. 가장 최근 사용 앱에서는 별도 윈도우 선택 없이 앱 전체 활성화를 수행한다.
9. 지정한 앱에서는 설정에 따라 가장 최근 사용 윈도우를 활성화하거나 지정 앱의 윈도우 선택 창을 표시한다.
10. Trace가 붙여넣기 이벤트를 보낸다.
11. 저장된 캡처가 있으면 전달 결과를 히스토리에 기록한다.

전달 대상 방식

설정의 deliveryTargetMode 값:

• chooseEachTime: 캡처 후 앱/윈도우 선택 창을 표시한다.
• mostRecentApp: 캡처 시작 직전의 전면 앱을 기억했다가 선택 창 없이 해당 앱으로 전달한다.
• fixedApp: 설정에 저장된 앱으로 바로 전달한다.

mostRecentApp은 자동 추천이 아니라 사용자가 설정에서 명시적으로 선택하는 고정 동작이다. 캡처 시작 직전 전면 앱이 Trace 자신이거나 일반 앱이 아니면 전달 실패로 처리한다.

fixedApp은 사용자가 설정에서 앱을 명시적으로 저장해야 한다. 지정 앱이 실행 중이지 않으면 앱을 자동 실행하지 않고 실패 알림을 보낸다.

지정 앱의 윈도우 처리 방식:

• mostRecentWindow: 지정 앱의 main window를 우선 활성화하고, 없으면 앱 전체 활성화로 붙여넣기를 보낸다.
• chooseWindow: 지정 앱의 윈도우 선택 창을 표시한다.

대상 앱 목록

대상 앱 목록은 NSWorkspace의 실행 중인 앱 목록을 기준으로 만든다.

표시 기준:

• 앱 이름이 있는 항목만 표시한다.
• 백그라운드 전용 프로세스는 제외한다.
• Trace 자신은 제외한다.
• 앱 아이콘과 앱 이름을 함께 표시한다.
• 현재 활성 앱은 우선 표시할 수 있다.

대상 윈도우 목록

기본 전달은 Accessibility API로 선택한 앱의 윈도우 목록을 읽어 사용자가 붙여넣을 윈도우를 고르게 한다.

표시 기준:

• 우선 Core Graphics 윈도우 목록으로 실제 화면에 떠 있는 일반 윈도우를 표시한다.
• 현재 Space뿐 아니라 현재 사용자 세션의 다른 Space에 있는 일반 윈도우도 표시한다.
• 각 보이는 윈도우는 Accessibility hit-test로 조작 가능한 윈도우와 다시 연결을 시도한다.
• Accessibility가 추가로 노출한 숨은 윈도우도 중복되지 않게 보강한다.
• 제목이 없는 윈도우도 선택할 수 있게 대체 이름을 부여한다.
• 제목이 없는 윈도우는 내부 보조 창이 섞이기 쉬우므로, 너무 작거나 사실상 투명한 창은 제외한다.
• 화면 기록 권한이 있으면 ScreenCaptureKit으로 각 윈도우 썸네일을 생성해 선택 화면에 함께 표시한다.
• 현재 메인 윈도우는 우선 표시한다.
• 윈도우보다 더 깊은 대상은 범용 규칙으로 다루지 않고, 앱별 전달 어댑터가 제공할 때만 표시한다.

권한

자동 전달에는 Accessibility 권한이 필요하다. 권한이 없으면 대상 앱 활성화와 붙여넣기 이벤트 전송을 시도하지 않는다.

권한이 없을 때의 동작:

• 전달용 클립보드는 유지한다.
• 설정이 저장을 포함하면 저장은 유지한다.
• 앱 전달 흐름에 처음 들어갈 때 macOS 손쉬운 사용 권한 요청을 트리거한다.
• Trace 자체 권한 안내 창은 표시하지 않는다.
• 저장된 캡처가 있으면 deliveryState는 failed로 기록한다.

결과 상태

deliveryState 값:

• none: 기본 캡처 모드
• skipped: 사용자가 대상 앱 선택을 건너뜀
• delivered: 대상 앱 활성화와 붙여넣기 이벤트 전송을 완료함
• failed: 권한 부족, 앱 활성화 실패, 이벤트 전송 실패

delivered는 붙여넣기 이벤트를 성공적으로 보냈다는 뜻이다. 대상 앱 내부에서 이미지가 실제로 첨부되었는지까지 100% 보장하지 않는다.

실패 처리

실패로 기록하는 경우:

• Accessibility 권한이 없음
• 대상 앱이 이미 종료됨
• 가장 최근 사용 앱을 찾을 수 없음
• 지정 앱이 설정되지 않음
• 지정 앱이 실행 중이지 않음
• 대상 앱 활성화 실패
• 붙여넣기 이벤트 전송 실패

실패 시 사용자에게 제공할 행동:

• 직접 붙여넣기 안내
• Finder에서 파일 보기

MVP 검증 대상 앱

MVP에서는 대표 앱에서 붙여넣기 기반 전달을 검증한다.

우선 대상:

• Slack
• Notion
• TextEdit
• Mail

대상 앱마다 붙여넣기 수용 방식이 다를 수 있으므로, 자동 전달은 앱별 커스텀 규칙 없이 best-effort 방식으로 다룬다.

앱별 전달 어댑터

MVP 이후 확장의 첫 예외로 cmux는 전용 어댑터를 둔다.

• 기본 앱 전달은 macOS 윈도우까지만 선택한다.
• cmux는 자체 CLI를 사용해 window -> workspace -> pane -> surface 계층을 읽는다.
• cmux 대상 선택 화면에는 surface 단위 대상을 추가로 표시한다.
• 사용자가 surface를 고르면 Trace가 cmux CLI의 surface.focus를 호출한 뒤 붙여넣기를 보낸다.
• cmux CLI를 찾을 수 없거나 socket 접근이 막혀 있으면 전용 대상은 표시하지 않고, 기본 윈도우 선택만 유지한다.

MVP 이후 확장

• 자주 쓰는 앱 즐겨찾기
• 추가 앱별 전달 어댑터
• 특정 앱의 첨부 API 또는 URL scheme 연동
• 전달 성공 여부를 앱별로 더 정확히 확인하는 방식