react-native-control-center 0.1.0

package/lib/commonjs/core/templates/ButtonControl.swift.hbs

@@ -0,0 +1,28 @@
+import AppIntents
+import SwiftUI
+import WidgetKit
+
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  {{pascalCase id}}Control.swift   (Controls/{{pascalCase id}}Control.swift)
+//  Button 컨트롤의 표시 정의 — 제어센터에 어떤 모양으로 보일지
+//  (탭했을 때 일어나는 일은 Intents/{{pascalCase id}}Intent.swift 참조)
+// ─────────────────────────────────────────────────────────────────────────
+
+struct {{pascalCase id}}Control: ControlWidget {
+    var body: some ControlWidgetConfiguration {
+        StaticControlConfiguration(
+            kind: "{{bundleId}}.{{id}}"
+        ) {
+            ControlWidgetButton(action: {{pascalCase id}}Intent()) {
+                Label("{{title}}", systemImage: "{{icon}}")
+                {{#if tint}}
+                    .tint(Color(hex: "{{tint}}"))
+                {{/if}}
+            }
+        }
+        .displayName("{{title}}")
+        {{#if description}}
+        .description("{{description}}")
+        {{/if}}
+    }
+}

package/lib/commonjs/core/templates/ButtonIntent.swift.hbs

@@ -0,0 +1,39 @@
+import AppIntents
+
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  {{pascalCase id}}Intent.swift   (Intents/{{pascalCase id}}Intent.swift)
+//  Button 탭 → 앱 열림까지의 흐름
+// ─────────────────────────────────────────────────────────────────────────
+//
+//  ① 사용자가 제어센터에서 "{{title}}" 버튼을 탭함
+//        ↓
+//  ② iOS가 위젯 익스텐션 프로세스를 깨워서 perform() 호출
+//        ↓
+//  ③ perform() 안에서:
+//       (a) ControlStore.shared.enqueueAction() 호출
+//             → App Group UserDefaults 큐에 이벤트 저장 (영구)
+//             → Darwin Notification 발송 (앱이 살아있으면 즉시 알림)
+//       (b) return .result()
+//        ↓
+//  ④ openAppWhenRun = true 이므로 iOS가 메인 앱을 포어그라운드로 띄움
+//        ↓
+//  ⑤ 메인 앱 시작/복귀 후 Native Module이 큐를 drain (Week 5에서 구현)
+//        ↓
+//  ⑥ JS의 ControlCenter.onAction((id) => { ... }) 콜백 발화
+//
+// ─────────────────────────────────────────────────────────────────────────
+
+struct {{pascalCase id}}Intent: AppIntent {
+    static let title: LocalizedStringResource = "{{title}}"
+    static let openAppWhenRun: Bool = true   // ④ 이 플래그가 메인 앱을 깨움
+
+    func perform() async throws -> some IntentResult {
+        // ③ (a): App Group 큐에 이벤트 기록 + Darwin 알림 발송
+        ControlStore.shared.enqueueAction(
+            id: "{{id}}",
+            deepLink: "{{deepLink}}"
+        )
+        // ③ (b): perform 종료. 이후 ④(앱 열기)는 iOS가 자동 처리
+        return .result()
+    }
+}

package/lib/commonjs/core/templates/ControlBundle.swift.hbs

@@ -0,0 +1,17 @@
+import WidgetKit
+import SwiftUI
+
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  ControlBundle.swift
+//  위젯 익스텐션 진입점 — iOS가 이 @main 구조체를 통해 모든 컨트롤을 인식.
+//  controls.ts에 선언된 모든 컨트롤이 여기 등록됨.
+// ─────────────────────────────────────────────────────────────────────────
+
+@main
+struct {{bundleStructName}}: WidgetBundle {
+    var body: some Widget {
+        {{#each controls}}
+        {{pascalCase id}}Control()
+        {{/each}}
+    }
+}

package/lib/commonjs/core/templates/ControlStore.swift.hbs

@@ -0,0 +1,149 @@
+import Foundation
+
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  ControlStore.swift   (위젯 + 메인 앱 양쪽에서 공유)
+//  위젯 익스텐션과 메인 앱 사이의 다리
+// ─────────────────────────────────────────────────────────────────────────
+//
+//  위젯과 앱은 서로 다른 프로세스(메모리 분리)이므로 변수로는 정보 공유 불가.
+//  대신 두 채널을 사용한다:
+//
+//   1. App Group UserDefaults
+//      - 같은 그룹 ID를 양쪽 entitlement에 등록한 두 프로세스가 공유하는
+//        영구 키-값 저장소
+//      - 데이터를 "남겨두는" 역할 (앱이 죽었다가 다시 살아도 살아남음)
+//
+//   2. Darwin Notification
+//      - 다윈 커널 수준의 글로벌 신호 (페이로드 없음)
+//      - "값이 바뀌었음!" 이라는 신호만 전달, 받은 쪽이 ①에서 새 값을 읽음
+//      - 앱이 살아있을 때만 의미 있음 (앱이 죽어있으면 신호 사라짐)
+//
+//  두 채널을 합치면: 영구 저장 + 즉시 알림 둘 다 충족.
+//
+//  자동 생성됨 — 직접 편집하지 마세요. 다음 prebuild 때 덮어써집니다.
+// ─────────────────────────────────────────────────────────────────────────
+
+public final class ControlStore {
+    public static let shared = ControlStore()
+
+    // 사용자 라이브러리 설정에서 주입된 값
+    public static let appGroupId = "{{appGroupId}}"
+    public static let darwinNotificationName = "{{appGroupId}}.event"
+
+    // 큐 저장 키 — 두 종류의 이벤트를 분리 저장
+    private static let actionQueueKey = "__rncc.actionQueue"        // Button 탭 이벤트
+    private static let stateChangeQueueKey = "__rncc.stateChangeQueue" // Toggle 변경 이벤트
+
+    private let defaults: UserDefaults
+
+    private init() {
+        // App Group UserDefaults 열기. 이게 실패하면 entitlement 미설정 의심.
+        guard let groupDefaults = UserDefaults(suiteName: ControlStore.appGroupId) else {
+            preconditionFailure(
+                "ControlStore: failed to open App Group UserDefaults for \(ControlStore.appGroupId). " +
+                "Verify the App Group entitlement is configured for both targets."
+            )
+        }
+        self.defaults = groupDefaults
+    }
+
+    // ─── Toggle 상태 R/W ─────────────────────────────────────────────────
+    //  Provider.currentValue() → getBool() (위젯이 "지금 ON?" 물어볼 때)
+    //  Toggle Intent.perform() → setBool() (사용자가 토글 누를 때)
+    //  메인 앱의 useControlState 훅 → 양쪽 다 사용 (Week 5)
+
+    public func getBool(_ key: String) -> Bool {
+        return defaults.bool(forKey: key)
+    }
+
+    public func setBool(_ key: String, value: Bool) {
+        defaults.set(value, forKey: key)
+    }
+
+    public func getValue<T>(_ key: String, default defaultValue: T) -> T {
+        return (defaults.object(forKey: key) as? T) ?? defaultValue
+    }
+
+    public func setValue(_ key: String, value: Any) {
+        defaults.set(value, forKey: key)
+    }
+
+    /// 라이브러리가 관리하는 toggle stateKey 목록 (codegen이 정적으로 주입).
+    /// dictionaryRepresentation()은 시스템 전역 도메인까지 섞여 나오므로
+    /// 우리가 선언한 키만 정확히 추리기 위해 이 화이트리스트를 쓴다.
+    public static let stateKeys: [String] = [{{#each stateKeys}}"{{this}}"{{#unless @last}}, {{/unless}}{{/each}}]
+
+    /// 선언된 stateKey들의 현재 값 스냅샷.
+    /// Native Module이 모듈 등록 시점에 JS로 넘겨, 콜드 스타트 직후에도
+    /// useControlState 첫 렌더에서 값을 동기로 쓸 수 있게 한다. (Week 6)
+    public func snapshot() -> [String: Any] {
+        var out: [String: Any] = [:]
+        for key in Self.stateKeys {
+            if let value = defaults.object(forKey: key) {
+                out[key] = value
+            }
+        }
+        return out
+    }
+
+    // ─── 이벤트 큐 (Widget → App) ────────────────────────────────────────
+    //  Button.perform()에서 enqueueAction()을 호출하면
+    //   (1) UserDefaults 큐에 이벤트 push
+    //   (2) Darwin notification 발송
+    //  메인 앱의 Native Module이 이 큐를 drain → JS 콜백 발화 (Week 5)
+
+    /// Button intent에서 호출.
+    func enqueueAction(id: String, deepLink: String) {
+        appendToQueue(
+            key: Self.actionQueueKey,
+            event: [
+                "id": id,
+                "deepLink": deepLink,
+                "t": Date().timeIntervalSince1970,
+            ]
+        )
+        postDarwinNotification()
+    }
+
+    /// Toggle intent에서 호출.
+    func enqueueStateChange(key: String, value: Any) {
+        appendToQueue(
+            key: Self.stateChangeQueueKey,
+            event: [
+                "key": key,
+                "value": value,
+                "t": Date().timeIntervalSince1970,
+            ]
+        )
+        postDarwinNotification()
+    }
+
+    /// 메인 앱의 Native Module이 호출 — 큐를 비우고 이벤트 배열 반환.
+    public func dequeueActionEvents() -> [[String: Any]] {
+        let events = (defaults.array(forKey: Self.actionQueueKey) as? [[String: Any]]) ?? []
+        defaults.removeObject(forKey: Self.actionQueueKey)
+        return events
+    }
+
+    public func dequeueStateChangeEvents() -> [[String: Any]] {
+        let events = (defaults.array(forKey: Self.stateChangeQueueKey) as? [[String: Any]]) ?? []
+        defaults.removeObject(forKey: Self.stateChangeQueueKey)
+        return events
+    }
+
+    // ─── 내부 ────────────────────────────────────────────────────────────
+
+    private func appendToQueue(key: String, event: [String: Any]) {
+        var queue = (defaults.array(forKey: key) as? [[String: Any]]) ?? []
+        queue.append(event)
+        defaults.set(queue, forKey: key)
+    }
+
+    /// Darwin notification 발송. Cross-process 즉시 신호.
+    /// 페이로드는 없고 "뭔가 바뀜!" 신호만 전달.
+    private func postDarwinNotification() {
+        let center = CFNotificationCenterGetDarwinNotifyCenter()
+        let name = CFNotificationName(Self.darwinNotificationName as CFString)
+        CFNotificationCenterPostNotification(center, name, nil, nil, true)
+    }
+}

package/lib/commonjs/core/templates/ToggleControl.swift.hbs

@@ -0,0 +1,60 @@
+import AppIntents
+import SwiftUI
+import WidgetKit
+
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  {{pascalCase id}}Control.swift   (Controls/{{pascalCase id}}Control.swift)
+//  Toggle 표시 흐름 (제어센터를 열 때마다)
+// ─────────────────────────────────────────────────────────────────────────
+//
+//  ① 사용자가 제어센터를 열거나 토글이 화면에 보이려 함
+//        ↓
+//  ② iOS가 Provider.currentValue() 호출 → "지금 ON 인지 OFF 인지?" 질의
+//        ↓
+//  ③ Provider가 ControlStore.shared.getBool("{{stateKey}}") 호출
+//        → App Group UserDefaults에서 현재 값 읽음
+//        ↓
+//  ④ iOS가 그 값(isOn)으로 ControlWidgetToggle을 그림
+//        - on이면 icons.on, off면 icons.off
+//        - on/off 색상도 분기
+//
+// ─────────────────────────────────────────────────────────────────────────
+
+struct {{pascalCase id}}Control: ControlWidget {
+    var body: some ControlWidgetConfiguration {
+        StaticControlConfiguration(
+            kind: "{{bundleId}}.{{id}}",
+            provider: {{pascalCase id}}Provider()       // ② 상태 질의 대상
+        ) { isOn in
+            ControlWidgetToggle(
+                "{{title}}",
+                isOn: isOn,                              // ④ Provider가 답한 값
+                action: {{pascalCase id}}Intent()        // 사용자가 탭하면 이게 실행
+            ) { isOn in
+                Label(
+                    "{{title}}",
+                    systemImage: isOn ? "{{icons.on}}" : "{{icons.off}}"
+                )
+                {{#if tint}}
+                .tint(Color(hex: isOn ? "{{tint.on}}" : "{{tint.off}}"))
+                {{/if}}
+            }
+        }
+        .displayName("{{title}}")
+        {{#if description}}
+        .description("{{description}}")
+        {{/if}}
+    }
+}
+
+extension {{pascalCase id}}Control {
+    struct {{pascalCase id}}Provider: ControlValueProvider {
+        // 미리보기/플레이스홀더용 기본값
+        var previewValue: Bool { false }
+
+        // ③ iOS가 토글을 그릴 때마다 호출. 공유 저장소에서 현재 상태를 읽어 반환.
+        func currentValue() async throws -> Bool {
+            return ControlStore.shared.getBool("{{stateKey}}")
+        }
+    }
+}

package/lib/commonjs/core/templates/ToggleIntent.swift.hbs

@@ -0,0 +1,49 @@
+import AppIntents
+
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  {{pascalCase id}}Intent.swift   (Intents/{{pascalCase id}}Intent.swift)
+//  Toggle 탭 → 상태 변경 흐름
+// ─────────────────────────────────────────────────────────────────────────
+//
+//  ① 사용자가 제어센터에서 "{{title}}" 토글을 탭함
+//        ↓
+//  ② iOS가 새 값을 결정 (현재 OFF면 true, ON이면 false)
+//        ↓
+//  ③ iOS가 {{pascalCase id}}Intent를 인스턴스화하고 self.value에 새 값 주입
+//        ↓
+//  ④ perform() 호출:
+//       (a) ControlStore.shared.setBool("{{stateKey}}", value)
+//             → App Group UserDefaults에 새 상태 저장 (먼저!)
+//       (b) ControlStore.shared.enqueueStateChange()
+//             → JS에 알릴 이벤트 큐에 기록
+//             → Darwin Notification 발송 (앱이 살아있으면 즉시 깨움)
+//        ↓
+//  ⑤ return .result() — perform 종료
+//        ↓
+//  ⑥ iOS가 토글을 새 값으로 다시 그림 (Provider 재호출)
+//        ↓
+//  ⑦ (앱이 실행 중이면) Native Module이 ④(b) 큐 drain → JS의
+//     ControlCenter.onStateChange("{{stateKey}}", v => ...) 콜백 발화 (Week 5)
+//
+// ─────────────────────────────────────────────────────────────────────────
+
+struct {{pascalCase id}}Intent: SetValueIntent {
+    static let title: LocalizedStringResource = "{{title}}"
+
+    @Parameter(title: "{{title}}")
+    var value: Bool                                  // ③ iOS가 자동 주입
+
+    func perform() async throws -> some IntentResult {
+        // ④ (a): 새 상태를 공유 저장소에 먼저 저장 (순서 중요)
+        ControlStore.shared.setBool("{{stateKey}}", value: value)
+
+        // ④ (b): JS 측에 변화를 알릴 이벤트 큐에 기록 + Darwin 알림 발송
+        ControlStore.shared.enqueueStateChange(
+            key: "{{stateKey}}",
+            value: value
+        )
+
+        // ⑤ 끝
+        return .result()
+    }
+}

package/lib/commonjs/core/types.d.ts

@@ -0,0 +1,14 @@
+import type { ButtonControl, ToggleControl } from '../src/types';
+export type ParsedButtonControl = ButtonControl & {
+    id: string;
+};
+export type ParsedToggleControl = ToggleControl & {
+    id: string;
+};
+export type ParsedControl = ParsedButtonControl | ParsedToggleControl;
+export declare class ParseError extends Error {
+    readonly filePath: string;
+    readonly line?: number | undefined;
+    readonly column?: number | undefined;
+    constructor(message: string, filePath: string, line?: number | undefined, column?: number | undefined);
+}

package/lib/commonjs/core/types.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParseError = void 0;
+class ParseError extends Error {
+    filePath;
+    line;
+    column;
+    constructor(message, filePath, line, column) {
+        const loc = line !== undefined ? ` (${filePath}:${line}:${column ?? 0})` : ` (${filePath})`;
+        super(`${message}${loc}`);
+        this.filePath = filePath;
+        this.line = line;
+        this.column = column;
+        this.name = 'ParseError';
+    }
+}
+exports.ParseError = ParseError;

package/lib/commonjs/core/validateSymbols.d.ts

@@ -0,0 +1,15 @@
+import type { ParsedControl } from './types';
+export interface UnknownSymbol {
+    controlId: string;
+    field: string;
+    name: string;
+}
+/** 알려진 SF Symbol인지 검사. */
+export declare function isKnownSymbol(name: string): boolean;
+/** 컨트롤 목록에서 알 수 없는 심볼 참조를 모두 수집. */
+export declare function collectUnknownSymbols(controls: ParsedControl[]): UnknownSymbol[];
+/**
+ * 알 수 없는 심볼을 console.warn으로 보고. (plugin/CLI가 빌드 중 호출)
+ * 하나도 없으면 아무것도 출력하지 않는다.
+ */
+export declare function warnUnknownSymbols(controls: ParsedControl[]): UnknownSymbol[];

package/lib/commonjs/core/validateSymbols.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isKnownSymbol = isKnownSymbol;
+exports.collectUnknownSymbols = collectUnknownSymbols;
+exports.warnUnknownSymbols = warnUnknownSymbols;
+const sf_symbols_data_1 = require("./sf-symbols-data");
+/** 알려진 SF Symbol인지 검사. */
+function isKnownSymbol(name) {
+    return sf_symbols_data_1.SF_SYMBOLS.has(name);
+}
+/** 컨트롤 목록에서 알 수 없는 심볼 참조를 모두 수집. */
+function collectUnknownSymbols(controls) {
+    const unknown = [];
+    for (const control of controls) {
+        if (control.type === 'button') {
+            if (!isKnownSymbol(control.icon)) {
+                unknown.push({ controlId: control.id, field: 'icon', name: control.icon });
+            }
+        }
+        else if (control.type === 'toggle') {
+            if (!isKnownSymbol(control.icons.on)) {
+                unknown.push({ controlId: control.id, field: 'icons.on', name: control.icons.on });
+            }
+            if (!isKnownSymbol(control.icons.off)) {
+                unknown.push({ controlId: control.id, field: 'icons.off', name: control.icons.off });
+            }
+        }
+    }
+    return unknown;
+}
+/**
+ * 알 수 없는 심볼을 console.warn으로 보고. (plugin/CLI가 빌드 중 호출)
+ * 하나도 없으면 아무것도 출력하지 않는다.
+ */
+function warnUnknownSymbols(controls) {
+    const unknown = collectUnknownSymbols(controls);
+    for (const u of unknown) {
+        console.warn(`[react-native-control-center] Control "${u.controlId}" uses "${u.name}" ` +
+            `for ${u.field}, which is not a known SF Symbol. ` +
+            `Check the spelling in SF Symbols.app — if it's a newer symbol this warning is safe to ignore.`);
+    }
+    return unknown;
+}

package/lib/commonjs/core/xcode/addSyncedFolder.d.ts

@@ -0,0 +1,28 @@
+import type { PBXProject } from 'xcode';
+import './types';
+export interface AddSyncedFolderOptions {
+    /** 위젯 타겟 uuid — 이 폴더의 1차 멤버 */
+    widgetTargetUuid: string;
+    /** 메인 앱 타겟 uuid — sharedFiles에 한해 추가 멤버 */
+    mainAppTargetUuid: string;
+    /** 폴더 이름 (사용자 ios/ 디렉토리 기준 상대 경로) */
+    folderName: string;
+    /** 메인 앱과 공유할 폴더 내 파일들 (폴더 기준 상대 경로) */
+    sharedFiles: string[];
+    /**
+     * 위젯 타겟의 Sources/Resources 자동 멤버십에서 제외할 파일들.
+     * Info.plist, *.entitlements 같이 build setting으로 따로 참조하는 파일은
+     * 자동 컴파일/복사에서 빼야 "Multiple commands produce" 충돌을 피한다.
+     */
+    excludedFromWidget?: string[];
+}
+/**
+ * Xcode 16+의 fileSystemSynchronizedGroups 기반 멤버십 처리.
+ *
+ * 동작:
+ *   1) PBXFileSystemSynchronizedRootGroup을 만들어 폴더와 위젯 타겟을 매핑
+ *   2) sharedFiles가 있으면 ExceptionSet을 만들어 메인 앱 타겟에 그 파일들을 추가 멤버십으로 부여
+ *
+ * xcode npm 패키지(@3.0.1)는 이 객체들을 모르므로 pbxproj 섹션을 직접 변형한다.
+ */
+export declare function addSyncedSourceFolder(project: PBXProject, options: AddSyncedFolderOptions): void;

package/lib/commonjs/core/xcode/addSyncedFolder.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addSyncedSourceFolder = addSyncedSourceFolder;
+require("./types");
+/**
+ * Xcode 16+의 fileSystemSynchronizedGroups 기반 멤버십 처리.
+ *
+ * 동작:
+ *   1) PBXFileSystemSynchronizedRootGroup을 만들어 폴더와 위젯 타겟을 매핑
+ *   2) sharedFiles가 있으면 ExceptionSet을 만들어 메인 앱 타겟에 그 파일들을 추가 멤버십으로 부여
+ *
+ * xcode npm 패키지(@3.0.1)는 이 객체들을 모르므로 pbxproj 섹션을 직접 변형한다.
+ */
+function addSyncedSourceFolder(project, options) {
+    const objects = project.hash.project.objects;
+    // 0) ExceptionSet들 만들기. 다음 두 종류:
+    //    - sharedFiles → 메인 앱이 추가 멤버로 가져갈 파일들
+    //    - excludedFromWidget → 위젯 자기 자신의 자동 멤버십에서 빼는 파일들 (Info.plist 등)
+    const exceptionRefs = [];
+    const exceptionSection = (objects['PBXFileSystemSynchronizedBuildFileExceptionSet'] ??= {});
+    if (options.sharedFiles.length > 0) {
+        const uuid = generateUuid(project);
+        const comment = `Exceptions for "${options.folderName}" folder in main app target`;
+        exceptionSection[uuid] = {
+            isa: 'PBXFileSystemSynchronizedBuildFileExceptionSet',
+            membershipExceptions: options.sharedFiles,
+            target: options.mainAppTargetUuid,
+        };
+        exceptionSection[`${uuid}_comment`] = comment;
+        exceptionRefs.push({ value: uuid, comment });
+    }
+    if (options.excludedFromWidget && options.excludedFromWidget.length > 0) {
+        const uuid = generateUuid(project);
+        const comment = `Exceptions for "${options.folderName}" folder in widget target`;
+        exceptionSection[uuid] = {
+            isa: 'PBXFileSystemSynchronizedBuildFileExceptionSet',
+            membershipExceptions: options.excludedFromWidget,
+            target: options.widgetTargetUuid,
+        };
+        exceptionSection[`${uuid}_comment`] = comment;
+        exceptionRefs.push({ value: uuid, comment });
+    }
+    // 1) SynchronizedRootGroup 객체 생성
+    const groupUuid = generateUuid(project);
+    const groupSection = (objects['PBXFileSystemSynchronizedRootGroup'] ??= {});
+    const groupComment = options.folderName;
+    const groupObject = {
+        isa: 'PBXFileSystemSynchronizedRootGroup',
+        path: options.folderName,
+        sourceTree: '"<group>"',
+    };
+    if (exceptionRefs.length > 0) {
+        groupObject.exceptions = exceptionRefs;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    groupSection[groupUuid] = groupObject;
+    groupSection[`${groupUuid}_comment`] = groupComment;
+    // 2) 위젯 타겟의 fileSystemSynchronizedGroups에 등록
+    const targetSection = project.pbxNativeTargetSection();
+    const widgetTarget = targetSection[options.widgetTargetUuid];
+    if (!widgetTarget || typeof widgetTarget === 'string') {
+        throw new Error(`Widget target ${options.widgetTargetUuid} not found.`);
+    }
+    const synced = widgetTarget
+        .fileSystemSynchronizedGroups ?? [];
+    synced.push({ value: groupUuid, comment: groupComment });
+    widgetTarget.fileSystemSynchronizedGroups = synced;
+}
+function generateUuid(project) {
+    return project.generateUuid();
+}

package/lib/commonjs/core/xcode/addTarget.d.ts

@@ -0,0 +1,25 @@
+import type { PBXProject, PBXNativeTarget } from 'xcode';
+import './types';
+export interface AddTargetOptions {
+    /** 타겟 이름. 예: "ControlCenterExtension" → 빌드되면 ControlCenterExtension.appex */
+    name: string;
+    /** 위젯의 bundle id. 관례상 메인 앱 id 뒤에 부속 단어 붙임. */
+    bundleId: string;
+}
+export interface AddTargetResult {
+    uuid: string;
+    target: PBXNativeTarget;
+}
+/**
+ * 빈 사용자 Xcode 프로젝트에 Widget Extension 타겟을 1개 추가한다.
+ *
+ * 내부적으로 xcode 패키지의 addTarget()을 호출.
+ * targetType="app_extension"을 주면 패키지가 알아서 productType을
+ * "com.apple.product-type.app-extension"으로 매핑해줌.
+ *
+ * 주의: 이 함수는 타겟 노드만 만든다.
+ *   - Frameworks 링크 → Day 3
+ *   - Source 멤버십 → Day 4
+ *   - 메인 앱에 임베드 → Day 5
+ */
+export declare function addWidgetExtensionTarget(project: PBXProject, options: AddTargetOptions): AddTargetResult;

package/lib/commonjs/core/xcode/addTarget.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addWidgetExtensionTarget = addWidgetExtensionTarget;
+require("./types");
+/**
+ * 빈 사용자 Xcode 프로젝트에 Widget Extension 타겟을 1개 추가한다.
+ *
+ * 내부적으로 xcode 패키지의 addTarget()을 호출.
+ * targetType="app_extension"을 주면 패키지가 알아서 productType을
+ * "com.apple.product-type.app-extension"으로 매핑해줌.
+ *
+ * 주의: 이 함수는 타겟 노드만 만든다.
+ *   - Frameworks 링크 → Day 3
+ *   - Source 멤버십 → Day 4
+ *   - 메인 앱에 임베드 → Day 5
+ */
+function addWidgetExtensionTarget(project, options) {
+    const { name, bundleId } = options;
+    const result = project.addTarget(name, // 타겟 이름
+    'app_extension', // → "com.apple.product-type.app-extension" 자동 매핑
+    name, // subfolder (=name으로 통일)
+    bundleId // 위젯 bundle id
+    );
+    // xcode 패키지의 addTarget()은 새 타겟에 빈 buildPhases 배열만 만들어준다.
+    // Sources / Frameworks / Resources 페이즈는 우리가 직접 만들어 줘야
+    // 나중에 framework이나 source 파일을 등록할 곳이 생긴다.
+    project.addBuildPhase([], 'PBXSourcesBuildPhase', 'Sources', result.uuid);
+    project.addBuildPhase([], 'PBXFrameworksBuildPhase', 'Frameworks', result.uuid);
+    project.addBuildPhase([], 'PBXResourcesBuildPhase', 'Resources', result.uuid);
+    return {
+        uuid: result.uuid,
+        target: result.pbxNativeTarget,
+    };
+}

package/lib/commonjs/core/xcode/buildSettings.d.ts

@@ -0,0 +1,14 @@
+import type { PBXProject } from 'xcode';
+import './types';
+/**
+ * 타겟의 모든 build configuration(Debug, Release 등)에 같은 설정값들을 일괄 적용한다.
+ *
+ * pbxproj 구조:
+ *   PBXNativeTarget(타겟)
+ *     └─ buildConfigurationList → XCConfigurationList(uuid)
+ *           └─ buildConfigurations: [Debug uuid, Release uuid, ...]
+ *                 └─ 각 XCBuildConfiguration에 buildSettings dict
+ *
+ * 같은 키로 이미 값이 있으면 덮어씀.
+ */
+export declare function setTargetBuildSettings(project: PBXProject, targetUuid: string, settings: Record<string, string>): void;