react-native-control-center 0.1.0

package/ios/RNControlCenter.swift

@@ -0,0 +1,195 @@
+import Foundation
+import React
+import WidgetKit
+
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  RNControlCenter.swift
+//  Native Module — 위젯이 만든 이벤트를 JS로 배달하는 다리
+// ─────────────────────────────────────────────────────────────────────────
+//
+//  두 가지 책임:
+//   1. Darwin notification observer 등록/해제 (위젯이 "이벤트 있음!" 신호 보냈을 때 받기)
+//   2. ControlStore의 큐를 drain해서 JS로 이벤트 발사
+//
+// ─────────────────────────────────────────────────────────────────────────
+
+@objc(RNControlCenter)
+class RNControlCenter: RCTEventEmitter {
+
+  // MARK: - 이벤트 이름 등록
+  //
+  // RN에게 "이 모듈은 이런 이름의 이벤트를 발사한다"고 미리 알려준다.
+  // 여기 없는 이름으로 sendEvent를 호출하면 RN이 경고를 찍고 JS는 못 받는다.
+
+  override func supportedEvents() -> [String]! {
+    return [
+      "ControlAction",       // Button 탭됨 → { id, deepLink, t }
+      "ControlStateChange",  // Toggle 바뀜 → { key, value, t }
+    ]
+  }
+
+  // MARK: - 초기화 스레드 정책
+  //
+  // 이 모듈은 UI를 만지지 않으므로 백그라운드 스레드에서 init 가능.
+  // false 명시 안 하면 RN 0.49+에서 콘솔 경고 + 메인 스레드로 강제됨.
+
+  @objc override static func requiresMainQueueSetup() -> Bool {
+    return false
+  }
+
+  // MARK: - 동기 상수 (Week 6)
+  //
+  // 모듈이 JS에 등록되는 시점에 한 번 평가되어 NativeModules.RNControlCenter에
+  // 프로퍼티로 붙는다. JS의 상태 캐시가 콜드 스타트 직후에도 첫 렌더부터
+  // 값을 동기로 쓸 수 있도록 현재 상태 스냅샷을 미리 넘긴다.
+
+  @objc override func constantsToExport() -> [AnyHashable: Any]! {
+    return ["initialState": ControlStoreRuntime.shared.snapshot()]
+  }
+
+  // MARK: - Lifecycle hooks
+  //
+  // RN이 자동으로 호출:
+  //   startObserving() — JS에서 첫 listener가 addListener() 했을 때
+  //   stopObserving()  — JS에서 마지막 listener가 제거됐을 때
+  //
+  // 중간 listener 변동(2개째 추가, 1개 제거 후에도 남음 등)은 RN이 내부적으로 처리하고
+  // 여기로 호출하지 않는다. 우리는 0→1, 1→0 전환만 신경 쓰면 됨.
+
+  // RCTEventEmitter는 공개 `hasListeners`를 제공하지 않으므로 직접 추적한다.
+  // RN이 startObserving(0→1) / stopObserving(1→0)만 호출하므로 이 플래그로 충분.
+  private var hasAnyListeners = false
+
+  override func startObserving() {
+    hasAnyListeners = true
+    registerDarwinObserver()
+
+    // ⚠️ 중요 — 앱이 죽어있다 위젯 탭으로 깬 시나리오를 위해 미리 한 번 drain.
+    // 그때의 Darwin 신호는 이미 사라졌지만 큐(UserDefaults)엔 이벤트가 남아 있음.
+    drainQueueAndSendEvents()
+  }
+
+  override func stopObserving() {
+    hasAnyListeners = false
+    unregisterDarwinObserver()
+  }
+
+  // MARK: - Darwin observer 등록/해제
+  //
+  // 위젯 익스텐션이 ControlStore.postDarwinNotification()으로 발사한 신호를 받기 위해
+  // 커널 레벨 Darwin notification center에 observer를 등록한다.
+  //
+  // 까다로운 부분: CFNotificationCenterAddObserver는 C API라서 콜백을
+  // "C 함수 포인터" 형태로만 받음. Swift 클래스 메서드를 직접 못 넘김.
+  // 우회: self를 raw pointer로 변환해서 observer 인자로 넘기고,
+  //       콜백 안에서 그 포인터를 다시 self로 복원한다.
+
+  private var observerRegistered = false
+
+  private func registerDarwinObserver() {
+    guard !observerRegistered else { return }
+
+    let center = CFNotificationCenterGetDarwinNotifyCenter()
+
+    // self의 메모리 주소를 C가 이해할 raw pointer로 변환.
+    // ARC 참조 카운트는 건드리지 않음 (Native Module은 앱 전체 수명 보장).
+    let observer = Unmanaged.passUnretained(self).toOpaque()
+
+    CFNotificationCenterAddObserver(
+      center,
+      observer,
+      { _, observerPtr, _, _, _ in
+        // 이 클로저는 캡처 없음 → C 함수 포인터로 변환됨.
+        // observerPtr = 위에서 넘긴 self의 주소.
+        guard let observerPtr = observerPtr else { return }
+        let module = Unmanaged<RNControlCenter>
+          .fromOpaque(observerPtr)
+          .takeUnretainedValue()
+
+        // C 콜백은 임의 스레드에서 발사. RN bridge 호출은 메인 스레드가 안전.
+        DispatchQueue.main.async {
+          module.drainQueueAndSendEvents()
+        }
+      },
+      ControlStoreRuntime.shared.darwinNotificationName as CFString,  // 들을 채널 이름
+      nil,                                              // object filter (안 씀)
+      .deliverImmediately
+    )
+
+    observerRegistered = true
+  }
+
+  private func unregisterDarwinObserver() {
+    guard observerRegistered else { return }
+
+    let center = CFNotificationCenterGetDarwinNotifyCenter()
+    let observer = Unmanaged.passUnretained(self).toOpaque()
+
+    CFNotificationCenterRemoveObserver(
+      center,
+      observer,
+      CFNotificationName(ControlStoreRuntime.shared.darwinNotificationName as CFString),
+      nil
+    )
+
+    observerRegistered = false
+  }
+
+  // MARK: - JS가 부르는 메서드
+  //
+  // 이 영역의 @objc func들은 RNControlCenter.mm의 RCT_EXTERN_METHOD와 1:1 매칭.
+  // 시그니처가 .mm 쪽과 어긋나면 RN이 런타임에 메서드를 못 찾고 호출 실패.
+
+  /// JS에서 useControlState 훅이 초기값 읽을 때 사용.
+  /// 예: const value = await RNControlCenter.getState('vpnEnabled')
+  @objc func getState(_ key: String,
+                      resolver resolve: @escaping RCTPromiseResolveBlock,
+                      rejecter reject: @escaping RCTPromiseRejectBlock) {
+    let value = ControlStoreRuntime.shared.getBool(key)
+    resolve(value)
+  }
+
+  /// JS에서 useControlState 훅이 setter로 호출할 때 사용.
+  /// 예: await RNControlCenter.setState('vpnEnabled', true)
+  /// App Group UserDefaults에 값을 쓰면 위젯이 다음 렌더링 때 그 값을 읽는다.
+  @objc func setState(_ key: String,
+                      value: Bool,
+                      resolver resolve: @escaping RCTPromiseResolveBlock,
+                      rejecter reject: @escaping RCTPromiseRejectBlock) {
+    // 1) 공유 저장소에 값 먼저 쓴다 (위젯이 다음 렌더링 때 이 값을 읽음).
+    ControlStoreRuntime.shared.setBool(key, value: value)
+
+    // 2) iOS에 "제어센터 컨트롤 다시 그려!" 요청. (Week 6)
+    //    이게 없으면 앱에서 setState로 값을 바꿔도 제어센터 토글은
+    //    옛날 그림 그대로 남아있다. WidgetKit의 ControlCenter API는 iOS 18+.
+    if #available(iOS 18.0, *) {
+      ControlCenter.shared.reloadAllControls()
+    }
+
+    resolve(nil)
+  }
+
+  // MARK: - 큐 비우기 + JS 발사
+  //
+  // ControlStore의 두 종류 큐(action / stateChange)를 비우고
+  // 각 이벤트를 supportedEvents에 등록된 이름으로 JS에 발사.
+  //
+  // hasAnyListeners 가드: JS가 안 듣고 있으면 큐를 만지지 않는다.
+  // 안 만지면 다음 listener가 등록될 때 startObserving 안에서 drain됨.
+
+  private func drainQueueAndSendEvents() {
+    guard hasAnyListeners else { return }
+
+    // 1) Button 탭 큐
+    let actions = ControlStoreRuntime.shared.dequeueActionEvents()
+    for action in actions {
+      sendEvent(withName: "ControlAction", body: action)
+    }
+
+    // 2) Toggle 변경 큐
+    let stateChanges = ControlStoreRuntime.shared.dequeueStateChangeEvents()
+    for change in stateChanges {
+      sendEvent(withName: "ControlStateChange", body: change)
+    }
+  }
+}

package/lib/commonjs/cli/runGenerate.d.ts

@@ -0,0 +1,22 @@
+export interface RunGenerateOptions {
+    /** 사용자 RN 프로젝트 루트. 기본 process.cwd() */
+    projectRoot?: string;
+    /** package.json에 설정 없을 때 콘솔에 출력할 안내 메시지를 끌지 여부 (테스트용) */
+    silent?: boolean;
+}
+export interface RunGenerateResult {
+    filesWritten: string[];
+    pbxprojPath: string;
+    widgetTargetUuid: string;
+    mainAppTargetUuid: string;
+}
+/**
+ * RN CLI(bare) 프로젝트에서 Expo 플러그인이 하던 일을 한 번에 실행.
+ *
+ * 1) projectRoot/package.json의 "rnControlCenter" 설정 읽기
+ * 2) ios/<App>.xcodeproj/project.pbxproj 찾기
+ * 3) controls.ts 파싱 → 파일 생성 → 디스크 쓰기
+ * 4) wireXcodeProject() 호출
+ * 5) project.writeSync()로 변경 저장
+ */
+export declare function runGenerate(opts?: RunGenerateOptions): RunGenerateResult;

package/lib/commonjs/cli/runGenerate.js

@@ -0,0 +1,173 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runGenerate = runGenerate;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const plist = __importStar(require("plist"));
+const parseControls_1 = require("../core/parseControls");
+const validateSymbols_1 = require("../core/validateSymbols");
+const generate_1 = require("../core/generate");
+const wire_1 = require("../core/xcode/wire");
+const inspect_1 = require("../core/xcode/inspect");
+const plugin_1 = require("../plugin");
+/**
+ * RN CLI(bare) 프로젝트에서 Expo 플러그인이 하던 일을 한 번에 실행.
+ *
+ * 1) projectRoot/package.json의 "rnControlCenter" 설정 읽기
+ * 2) ios/<App>.xcodeproj/project.pbxproj 찾기
+ * 3) controls.ts 파싱 → 파일 생성 → 디스크 쓰기
+ * 4) wireXcodeProject() 호출
+ * 5) project.writeSync()로 변경 저장
+ */
+function runGenerate(opts = {}) {
+    const projectRoot = opts.projectRoot ?? process.cwd();
+    const config = readPluginConfig(projectRoot);
+    const iosRoot = path.join(projectRoot, 'ios');
+    if (!fs.existsSync(iosRoot)) {
+        throw new Error(`[rn-control-center] ios/ folder not found at ${iosRoot}. Are you in an RN project root?`);
+    }
+    const pbxprojPath = findPbxprojPath(iosRoot);
+    const bundleId = config.bundleId ?? readBundleIdFromInfoPlist(iosRoot);
+    const extensionName = config.extensionName ?? 'ControlCenterExtension';
+    // 1) Parse controls
+    const controlsAbs = path.resolve(projectRoot, config.controls);
+    if (!fs.existsSync(controlsAbs)) {
+        throw new Error(`[rn-control-center] controls file not found: ${controlsAbs}`);
+    }
+    const controls = (0, parseControls_1.parseControlsFile)(controlsAbs);
+    // 1b) 심볼 오타 경고 (빌드는 막지 않음)
+    (0, validateSymbols_1.warnUnknownSymbols)(controls);
+    // 2) Generate files
+    const files = (0, generate_1.generateNativeFiles)({
+        controls,
+        bundleId,
+        urlScheme: config.urlScheme,
+        ...(config.appGroupId !== undefined && { appGroupId: config.appGroupId }),
+        extensionName,
+    });
+    const filesWritten = [];
+    for (const file of files) {
+        const fullPath = path.join(iosRoot, file.path);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, file.content);
+        filesWritten.push(fullPath);
+    }
+    // 2b) 메인 앱 Info.plist에 런타임 스토어용 키 주입 (Expo 플러그인과 동일).
+    //     Native Module(Pod)이 App Group ID / stateKeys를 여기서 읽는다.
+    const appGroupId = config.appGroupId ?? (0, generate_1.defaultAppGroupId)(bundleId);
+    injectMainAppInfoPlistKeys(iosRoot, pbxprojPath, {
+        RNControlCenterAppGroup: appGroupId,
+        RNControlCenterStateKeys: (0, generate_1.collectStateKeys)(controls),
+    });
+    // 3) Wire pbxproj
+    const project = (0, inspect_1.loadProject)(pbxprojPath);
+    const sharedFiles = (0, plugin_1.deriveSharedFiles)(files, extensionName);
+    const widgetBundleId = `${bundleId}.${extensionName.toLowerCase()}`;
+    const { widgetTargetUuid, mainAppTargetUuid } = (0, wire_1.wireXcodeProject)(project, {
+        mainAppBundleId: bundleId,
+        widgetTargetName: extensionName,
+        widgetBundleId,
+        sharedFiles,
+        ...(config.deploymentTarget !== undefined && {
+            deploymentTarget: config.deploymentTarget,
+        }),
+        ...(config.swiftVersion !== undefined && { swiftVersion: config.swiftVersion }),
+    });
+    fs.writeFileSync(pbxprojPath, project.writeSync());
+    return { filesWritten, pbxprojPath, widgetTargetUuid, mainAppTargetUuid };
+}
+function readPluginConfig(projectRoot) {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+        throw new Error(`[rn-control-center] package.json not found at ${pkgPath}. Run from RN project root.`);
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const cfg = pkg['rnControlCenter'];
+    if (!cfg || typeof cfg !== 'object') {
+        throw new Error('[rn-control-center] No "rnControlCenter" key in package.json. ' +
+            'Add { "controls": "./src/controls.ts", "urlScheme": "myapp" }.');
+    }
+    if (!cfg.controls || typeof cfg.controls !== 'string') {
+        throw new Error('[rn-control-center] package.json rnControlCenter.controls is required.');
+    }
+    if (!cfg.urlScheme || typeof cfg.urlScheme !== 'string') {
+        throw new Error('[rn-control-center] package.json rnControlCenter.urlScheme is required.');
+    }
+    return cfg;
+}
+function findPbxprojPath(iosRoot) {
+    const entries = fs.readdirSync(iosRoot);
+    const xcodeproj = entries.find((e) => e.endsWith('.xcodeproj'));
+    if (!xcodeproj) {
+        throw new Error(`[rn-control-center] No *.xcodeproj found inside ${iosRoot}.`);
+    }
+    return path.join(iosRoot, xcodeproj, 'project.pbxproj');
+}
+/**
+ * 메인 앱 타겟의 Info.plist에 키를 병합 저장.
+ * bare RN 레이아웃은 ios/<AppName>/Info.plist (AppName = .xcodeproj 이름).
+ * Info.plist를 못 찾으면 조용히 건너뛴다 (라이브러리가 빌드를 막지 않도록).
+ */
+function injectMainAppInfoPlistKeys(iosRoot, pbxprojPath, keys) {
+    // pbxprojPath = ios/<App>.xcodeproj/project.pbxproj → <App> 추출
+    const appName = path.basename(path.dirname(pbxprojPath)).replace(/\.xcodeproj$/, '');
+    const plistPath = path.join(iosRoot, appName, 'Info.plist');
+    if (!fs.existsSync(plistPath))
+        return;
+    const parsed = plist.parse(fs.readFileSync(plistPath, 'utf-8'));
+    const merged = { ...parsed, ...keys };
+    fs.writeFileSync(plistPath, plist.build(merged));
+}
+function readBundleIdFromInfoPlist(iosRoot) {
+    // RN CLI 프로젝트엔 ios/<AppName>/Info.plist에 CFBundleIdentifier가 적혀있다.
+    // 보통 $(PRODUCT_BUNDLE_IDENTIFIER) 변수 형태인 경우가 많아 fallback 필요.
+    const subdirs = fs
+        .readdirSync(iosRoot, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
+        .map((d) => d.name);
+    for (const dir of subdirs) {
+        const plistPath = path.join(iosRoot, dir, 'Info.plist');
+        if (!fs.existsSync(plistPath))
+            continue;
+        const content = fs.readFileSync(plistPath, 'utf-8');
+        const match = content.match(/<key>CFBundleIdentifier<\/key>\s*<string>([^<]+)<\/string>/);
+        if (match && match[1] && !match[1].includes('$(')) {
+            return match[1];
+        }
+    }
+    throw new Error('[rn-control-center] Could not infer bundleId from any Info.plist. ' +
+        'Set "bundleId" explicitly in package.json rnControlCenter section.');
+}

package/lib/commonjs/core/generate/entitlements.d.ts

@@ -0,0 +1,17 @@
+export interface GenerateEntitlementsOptions {
+    /** 메인 앱과 위젯이 공유할 App Group ID. */
+    appGroupId: string;
+    /** 기존 엔타이틀먼트와 병합할 키 (옵션). */
+    merge?: Record<string, unknown>;
+}
+/**
+ * 메인 앱 + 위젯 익스텐션이 동일한 entitlements를 가져야
+ * App Group UserDefaults가 둘 사이에 공유됨.
+ *
+ * 같은 파일을 두 타겟이 참조하든, 똑같은 내용으로 두 파일을 두든 무방.
+ */
+export declare function generateAppGroupEntitlements(opts: GenerateEntitlementsOptions): string;
+/**
+ * 기존 entitlement 파일이 있으면 그 위에 App Group을 안전하게 병합.
+ */
+export declare function mergeAppGroupIntoEntitlements(existingPlistXml: string, appGroupId: string): string;

package/lib/commonjs/core/generate/entitlements.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAppGroupEntitlements = generateAppGroupEntitlements;
+exports.mergeAppGroupIntoEntitlements = mergeAppGroupIntoEntitlements;
+const plist_1 = __importDefault(require("plist"));
+/**
+ * 메인 앱 + 위젯 익스텐션이 동일한 entitlements를 가져야
+ * App Group UserDefaults가 둘 사이에 공유됨.
+ *
+ * 같은 파일을 두 타겟이 참조하든, 똑같은 내용으로 두 파일을 두든 무방.
+ */
+function generateAppGroupEntitlements(opts) {
+    const root = {
+        'com.apple.security.application-groups': [opts.appGroupId],
+        ...(opts.merge ?? {}),
+    };
+    return plist_1.default.build(root, { indent: '\t' });
+}
+/**
+ * 기존 entitlement 파일이 있으면 그 위에 App Group을 안전하게 병합.
+ */
+function mergeAppGroupIntoEntitlements(existingPlistXml, appGroupId) {
+    const parsed = plist_1.default.parse(existingPlistXml);
+    const existing = parsed['com.apple.security.application-groups'] ?? [];
+    const merged = Array.from(new Set([...existing, appGroupId]));
+    parsed['com.apple.security.application-groups'] = merged;
+    return plist_1.default.build(parsed, { indent: '\t' });
+}

package/lib/commonjs/core/generate/index.d.ts

@@ -0,0 +1,30 @@
+import { defaultAppGroupId, collectStateKeys, type GeneratedFile } from './swift';
+import type { ParsedControl } from '../types';
+export interface GenerateNativeOptions {
+    controls: ParsedControl[];
+    /** 메인 앱 bundle ID (예: "com.acme.app"). */
+    bundleId: string;
+    /** 딥링크 URL scheme (예: "acme"). */
+    urlScheme: string;
+    /** App Group 식별자. 미지정 시 `group.{bundleId}.controls`. */
+    appGroupId?: string;
+    /** Widget Extension 디렉터리 이름. 기본 "ControlCenterExtension". */
+    extensionName?: string;
+    /** Bundle struct 이름. 기본 "ControlCenterBundle". */
+    bundleStructName?: string;
+}
+export type FileTarget = 'extension' | 'app' | 'shared';
+export interface NativeFile {
+    /** 출력 상대 경로 (예: "ControlCenterExtension/Controls/QuickNoteControl.swift"). */
+    path: string;
+    content: string;
+    /** 어느 타겟에 멤버십을 부여해야 하는지 — Week 3 pbxproj 작업에서 사용. */
+    target: FileTarget;
+}
+/**
+ * 라이브러리의 단일 코드 생성 진입점.
+ * Swift 파일 + Info.plist + entitlement 두 파일을 한꺼번에 만들어 반환.
+ */
+export declare function generateNativeFiles(opts: GenerateNativeOptions): NativeFile[];
+export { defaultAppGroupId, collectStateKeys };
+export type { GeneratedFile };

package/lib/commonjs/core/generate/index.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectStateKeys = exports.defaultAppGroupId = void 0;
+exports.generateNativeFiles = generateNativeFiles;
+const swift_1 = require("./swift");
+Object.defineProperty(exports, "defaultAppGroupId", { enumerable: true, get: function () { return swift_1.defaultAppGroupId; } });
+Object.defineProperty(exports, "collectStateKeys", { enumerable: true, get: function () { return swift_1.collectStateKeys; } });
+const plist_1 = require("./plist");
+const entitlements_1 = require("./entitlements");
+/**
+ * 라이브러리의 단일 코드 생성 진입점.
+ * Swift 파일 + Info.plist + entitlement 두 파일을 한꺼번에 만들어 반환.
+ */
+function generateNativeFiles(opts) {
+    const extName = opts.extensionName ?? 'ControlCenterExtension';
+    const appGroupId = opts.appGroupId ?? (0, swift_1.defaultAppGroupId)(opts.bundleId);
+    const files = [];
+    // 1) Swift sources
+    const swiftFiles = (0, swift_1.generateSwiftFiles)({
+        controls: opts.controls,
+        bundleId: opts.bundleId,
+        urlScheme: opts.urlScheme,
+        appGroupId,
+        bundleStructName: opts.bundleStructName,
+    });
+    for (const f of swiftFiles) {
+        // ControlStore + Intents는 두 타겟이 함께 가져야 함 (양방향 통신).
+        // ControlBundle, Controls는 위젯 익스텐션 전용.
+        const target = isSharedSwiftFile(f.path) ? 'shared' : 'extension';
+        files.push({
+            path: `${extName}/${f.path}`,
+            content: f.content,
+            target,
+        });
+    }
+    // 2) Widget Extension Info.plist
+    files.push({
+        path: `${extName}/Info.plist`,
+        content: (0, plist_1.generateExtensionInfoPlist)({ extensionBundleName: extName }),
+        target: 'extension',
+    });
+    // 3) Entitlements — 두 타겟 동일
+    const entitlements = (0, entitlements_1.generateAppGroupEntitlements)({ appGroupId });
+    files.push({
+        path: `${extName}/${extName}.entitlements`,
+        content: entitlements,
+        target: 'extension',
+    });
+    files.push({
+        path: `${extName}/MainApp.entitlements`,
+        content: entitlements,
+        target: 'app',
+    });
+    return files;
+}
+function isSharedSwiftFile(swiftPath) {
+    return swiftPath === 'ControlStore.swift' || swiftPath.startsWith('Intents/');
+}

package/lib/commonjs/core/generate/plist.d.ts

@@ -0,0 +1,13 @@
+export interface GeneratePlistOptions {
+    /** Widget Extension의 bundle ID. 디스플레이 이름 보정에 쓰임. */
+    extensionBundleName?: string;
+    /** SDK 호환을 위한 추가 키. 사용자 커스텀 가능. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Widget Extension용 Info.plist 문자열 생성.
+ *
+ * NSExtensionPointIdentifier = com.apple.widgetkit-extension 이 핵심.
+ * iOS가 이 값을 보고 ControlWidget으로 인식.
+ */
+export declare function generateExtensionInfoPlist(opts?: GeneratePlistOptions): string;

package/lib/commonjs/core/generate/plist.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateExtensionInfoPlist = generateExtensionInfoPlist;
+const plist_1 = __importDefault(require("plist"));
+/**
+ * Widget Extension용 Info.plist 문자열 생성.
+ *
+ * NSExtensionPointIdentifier = com.apple.widgetkit-extension 이 핵심.
+ * iOS가 이 값을 보고 ControlWidget으로 인식.
+ */
+function generateExtensionInfoPlist(opts = {}) {
+    // GENERATE_INFOPLIST_FILE=NO 일 때 Xcode가 표준 키를 자동 채워주지 않으므로
+    // AppIntentsSSU 같은 후속 빌드 도구가 요구하는 최소 키들을 우리가 직접 넣어준다.
+    const root = {
+        CFBundleDevelopmentRegion: '$(DEVELOPMENT_LANGUAGE)',
+        CFBundleExecutable: '$(EXECUTABLE_NAME)',
+        CFBundleIdentifier: '$(PRODUCT_BUNDLE_IDENTIFIER)',
+        CFBundleInfoDictionaryVersion: '6.0',
+        CFBundleName: '$(PRODUCT_NAME)',
+        CFBundlePackageType: '$(PRODUCT_BUNDLE_PACKAGE_TYPE)',
+        CFBundleShortVersionString: '1.0',
+        CFBundleVersion: '1',
+        NSExtension: {
+            NSExtensionPointIdentifier: 'com.apple.widgetkit-extension',
+        },
+    };
+    if (opts.extensionBundleName) {
+        root.CFBundleDisplayName = opts.extensionBundleName;
+    }
+    if (opts.extra) {
+        Object.assign(root, opts.extra);
+    }
+    return plist_1.default.build(root, { indent: '  ' });
+}

package/lib/commonjs/core/generate/swift.d.ts

@@ -0,0 +1,22 @@
+import type { ParsedControl } from '../types';
+export interface GenerateOptions {
+    controls: ParsedControl[];
+    bundleId: string;
+    urlScheme: string;
+    appGroupId?: string;
+    bundleStructName?: string;
+}
+export declare function defaultAppGroupId(bundleId: string): string;
+/**
+ * 토글 컨트롤들의 stateKey 목록.
+ * - 생성된 ControlStore.swift의 정적 화이트리스트로 박힘
+ * - Native Module의 snapshot() 정제를 위해 메인 앱 Info.plist
+ *   ("RNControlCenterStateKeys")로도 주입됨
+ */
+export declare function collectStateKeys(controls: ParsedControl[]): string[];
+export interface GeneratedFile {
+    path: string;
+    content: string;
+}
+export declare function pascalCase(str: string): string;
+export declare function generateSwiftFiles(opts: GenerateOptions): GeneratedFile[];