Chaeguevara·Chaeguevara/Skills/macos-native/SKILL.md

macos-native

Skill0 starsChanged 5 months agoNo licenceView on GitHub

네이티브 macOS + Apple 런타임/데이터 (AppKit / SwiftUI / sandbox / filesystem / SwiftData / xcstrings) 의 일곱 가지 함정을 증상별로 진단하고 맞는 fix shard 로 라우팅한다 — native macOS + Apple runtime/data gotchas. (1) NSPanel overlay 가 사용자가 *실수로 못 닫게* 해야 함 (phase boundary / break / forced confirmation) — 백드롭 클릭 / Return / Escape 로 너무 쉽게 닫힘 ("알림이 너무 쉽게 꺼진다" / "정확히 버튼을 눌러야 닫히게" / "키보드로 못 끄게") → blocking-dismiss (`canBecomeKey=false` + `canBecomeMain=false` subclass, no backdrop `.onTapGesture`, no Return/Escape `.keyboardShortcut`, `becomesKeyOnlyIfNeeded=true` — 네 layer defense in depth). (2) 일시적 alert/overlay 가 *모든 앱 & 모든 Space (full-screen 포함)* 위에 떠야 함 ("알림이 약해서 자꾸 놓친다" / "화면 전체 덮는 alert 같은 게 필요하다") → screensaver-overlay (NSPanel `level = .screenSaver` + `collectionBehavior = [.canJoinAllSpaces, .stationary, .fullScreenAuxiliary]` + 모든 NSScreen union frame, `orderFrontRegardless()`). (3) "빌드는 되는데 화면이 안 뜬다" / "프로세스는 살아있는데 보이지 않는다" / "100% CPU 만 잡힌다" / "앱이 안 뜬다" / "구동 안 됨" → app-launch-diagnosis (`ps -p $PID -o pid,state,%cpu`, `sample $PID 2`, `CGWindowList` bounds, `screencapture -D N` 외부 디스플레이). (4) sandboxed Save/Export panel 이 silent 하게 아무것도 안 함 ("Export 눌러도 반응 없음", console 메시지 "your app has the User Selected File Read entitlement but it needs User Selected File Read/Write to display save panels", NSSavePanel / `.fileExporter` 안 뜸) → sandbox-savepanel-entitlement (`.entitlements` 의 `com.apple.security.files.user-selected.read-only` → `...read-write`). (5) Korean 파일명이 JS/regex 에서 안 잡힘 (macOS NFD vs JS NFC) — `readdirSync` 로 순회하며 `/2018년_상반기/` 매칭이 0개 → nfd-korean-filenames (`rawFile.normalize('NFC')` before matching). (6) SwiftData `@Model` 에 새 필드를 추가할 때 lightweight migration 이 조용히 실패 — 출시 앱이 OTA 업데이트 후 빈 데이터로 열리거나 ModelContainer 가 fresh in-memory store 로 fallback 하거나 crash ("업데이트하고 데이터가 사라졌다", "ModelContainer fallback to in-memory" 로그) → swiftdata-add-field-migration (새 프로퍼티 Optional 선언 + `asValue` 에서 `?? .default` 폴백 + Codable `init(from:)` 에서 `decodeIfPresent` — 3-layer). (7) Xcode `.xcstrings` (String Catalog / Localizable.xcstrings) JSON 을 Python 으로 batch 편집할 때 git diff 가 수천 줄 churn 으로 터짐 ("xcstrings 일괄 편집", localization, "한꺼번에 20개 KO 번역 추가해줘") → xcstrings-batch-edit (`json.dumps` 에 `ensure_ascii=False` + Xcode 의 space-colon-space separator 를 명시 + 기존 키 순서 건드리지 말고 append-only). 트리거 — NSPanel, `.screenSaver`, `canBecomeKey`, `sample`, `CGWindowList`, `com.apple.security.files.user-selected.read-write`, NFD/NFC, `readdirSync`, SwiftData, `@Model`, ModelContainer, lightweight migration, `decodeIfPresent`, `.xcstrings`, String Catalog, `json.dumps`, `separators`, "앱이 안 뜬다", "Export 눌러도 반응 없음", "화면 전체 덮는 alert", "업데이트하고 데이터가 사라졌다", "xcstrings 일괄 편집".