react-native-control-center 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 darby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,415 @@
+# react-native-control-center
+
+iOS 18+ Control Center custom controls for React Native — declare in TypeScript, zero Swift required.
+
+![status](https://img.shields.io/badge/status-v0.1.0-brightgreen) ![iOS](https://img.shields.io/badge/iOS-18%2B-blue) ![license](https://img.shields.io/badge/license-MIT-green)
+
+> **v0.1.0.** Build-time pipeline (codegen + pbxproj wiring + Expo plugin + CLI) and runtime native module (Darwin observer → queue drain → JS events) are complete and compile end-to-end against the real iOS 18 SDK. The runtime hook gives synchronous initial state via a cache and re-renders Control Center on programmatic state change; a 5,000+ SF Symbol set backs build-time spell-check. See [Installation](#installation) and the [Roadmap](#roadmap).
+
+---
+
+## What it does
+
+Declare controls in TypeScript:
+
+```ts
+// src/controls.ts
+import { defineControls } from 'react-native-control-center';
+
+export default defineControls({
+  quickNote: {
+    type: 'button',
+    title: 'Quick Note',
+    icon: 'square.and.pencil',
+  },
+  vpnToggle: {
+    type: 'toggle',
+    title: 'VPN',
+    icons: { on: 'lock.fill', off: 'lock.open' },
+    stateKey: 'vpnEnabled',
+  },
+});
+```
+
+Add one line to `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      ["react-native-control-center", {
+        "controls": "./src/controls.ts",
+        "urlScheme": "myapp"
+      }]
+    ]
+  }
+}
+```
+
+Run `npx expo prebuild` and the library:
+
+- generates a Widget Extension target
+- writes the `ControlWidget` + `AppIntent` Swift files
+- links `AppIntents.framework` and `WidgetKit.framework`
+- wires up App Group entitlement for two-way state sync
+- registers a URL scheme for deep linking
+
+React to taps in your app:
+
+```ts
+import { ControlCenter, useControlState } from 'react-native-control-center';
+
+// Button taps
+ControlCenter.onAction(({ id }) => {
+  if (id === 'quickNote') navigation.navigate('NewNote');
+});
+
+// Bidirectional toggle state
+const [isVPN, setVPN] = useControlState<boolean>('vpnEnabled');
+```
+
+---
+
+## Requirements
+
+| | Minimum |
+| --- | --- |
+| iOS (controls visible) | **18.0+** — on iOS 17 and below the library loads and no-ops; controls just don't appear |
+| Xcode | **16+** (ships the iOS 18 SDK with `ControlWidget` / WidgetKit `ControlCenter`) |
+| React Native | **0.74+** |
+| Expo (optional) | **SDK 54+** if you use the config plugin |
+
+Android is a safe no-op today; a Quick Settings Tiles backend is planned (see [Roadmap](#roadmap)).
+
+## Installation
+
+```bash
+npm install react-native-control-center
+```
+
+**Expo** — add the config plugin to `app.json`, then prebuild:
+
+```json
+{ "expo": { "plugins": [["react-native-control-center", {
+  "controls": "./src/controls.ts",
+  "urlScheme": "myapp"
+}]] } }
+```
+
+```bash
+npx expo prebuild --clean && npx expo run:ios
+```
+
+**Bare React Native** — add a `rnControlCenter` block to `package.json`, then run the CLI:
+
+```json
+{ "rnControlCenter": { "controls": "./src/controls.ts", "urlScheme": "myapp" } }
+```
+
+```bash
+npx rn-control-center generate && cd ios && pod install && cd .. && npx react-native run-ios
+```
+
+See runnable references in [`examples/expo`](examples/expo) and [`examples/bare-rn`](examples/bare-rn).
+
+## Why this exists
+
+Apple's iOS 18 Control Widgets are powerful, but wiring them up from React Native currently means:
+
+1. Opening Xcode
+2. Adding a Widget Extension target
+3. Writing SwiftUI `ControlWidget` by hand
+4. Defining an `AppIntent`
+5. Configuring an App Group
+6. Setting up a URL scheme
+7. Bridging taps back to JS
+
+`@bacons/apple-targets` solves step 1 — but leaves you with Swift, plists, and entitlements to manage yourself.
+
+This library takes a declarative TypeScript config and generates the full native extension, including the pieces needed for two-way state sync with your React Native app.
+
+---
+
+## How it works
+
+There are two distinct flows worth understanding: what happens **at build time**
+when you run `expo prebuild` (or `rn-control-center generate`), and what happens
+**at runtime** when a user taps a control in Control Center.
+
+### Build-time pipeline
+
+```
+[ npx expo prebuild ]                      [ npx rn-control-center generate ]
+        │                                              │
+        ▼                                              ▼
+ Expo reads app.json plugins              cli/bin reads package.json
+        │                                              │
+        ▼                                              ▼
+ plugin/index.ts                          cli/runGenerate.ts
+   withControlCenter(config, props)         runGenerate({ projectRoot })
+        │                                              │
+        ├── validateProps()                            │
+        │                                              │
+        ├── withDangerousMod(...) ────────┐            │
+        │       parseControlsFile()       │            │
+        │       generateNativeFiles()     │            │
+        │       fs.writeFileSync(...)     │            │
+        │                                 │            │
+        └── withXcodeProject(...) ────────┘            │
+                wireXcodeProject(project, opts)        │
+                                                       │
+                                                       ▼
+        ┌──── parseControlsFile()  ◄────  reads ./src/controls.ts and turns
+        │                                  the defineControls({...}) literal
+        │                                  into ParsedControl[] (Babel AST)
+        │
+        ├──── generateNativeFiles()  ──►  emits 8 NativeFile records:
+        │                                  • ControlBundle.swift
+        │                                  • ControlStore.swift
+        │                                  • Controls/<Name>Control.swift × N
+        │                                  • Intents/<Name>Intent.swift × N
+        │                                  • Info.plist
+        │                                  • <ext>.entitlements (widget)
+        │                                  • MainApp.entitlements (main app)
+        │
+        ├──── fs.writeFileSync(...)  ──►  writes the eight files into
+        │                                  ios/ControlCenterExtension/
+        │
+        └──── wireXcodeProject(...)  ──►  mutates project.pbxproj:
+                  ├── addWidgetExtensionTarget()       app-extension target
+                  │                                    + auto PBXCopyFilesBuildPhase
+                  │                                      embedding the .appex
+                  ├── linkFrameworks(widget,           one PBXFileReference,
+                  │     ['WidgetKit','SwiftUI',         one PBXBuildFile per
+                  │      'AppIntents'])                 target's Frameworks phase
+                  ├── linkFrameworks(mainApp,
+                  │     ['AppIntents'])
+                  ├── addSyncedSourceFolder()          PBXFileSystemSynchronizedRootGroup
+                  │                                    + 2 ExceptionSets:
+                  │                                      • shared files → main app
+                  │                                      • plist/entitlements → exclude widget
+                  ├── setTargetBuildSettings(widget,   IPHONEOS_DEPLOYMENT_TARGET=18.0,
+                  │     {...})                          INFOPLIST_FILE,
+                  │                                     CODE_SIGN_ENTITLEMENTS,
+                  │                                     GENERATE_INFOPLIST_FILE=NO, ...
+                  ├── setTargetBuildSettings(mainApp,  CODE_SIGN_ENTITLEMENTS,
+                  │     {...})                          IPHONEOS_DEPLOYMENT_TARGET≥16.0
+                  └── verifyEmbedded()                  sanity check
+                                                       │
+                                                       ▼
+                                                 project.writeSync()
+                                                       │
+                                                       ▼
+                                                 CocoaPods install
+                                                       │
+                                                       ▼
+                                                 ios/ ready to xcodebuild
+```
+
+### Runtime — Button tap (e.g. "Quick Note")
+
+```
+①  user taps "Quick Note" in Control Center
+        │
+        ▼
+②  iOS wakes the widget extension process
+        │
+        ▼
+③  QuickNoteIntent.perform() runs (in widget process)
+        │   ControlStore.shared.enqueueAction(id, deepLink)
+        │     └── push event to App Group UserDefaults queue
+        │     └── post a Darwin notification
+        │   return .result()
+        │
+        ▼
+④  iOS sees `static let openAppWhenRun: Bool = true`
+        └── brings the main app to the foreground
+        │
+        ▼
+⑤  Main app starts/resumes
+        └── (Week 5) Native Module observes the Darwin notification,
+            drains the App Group queue, emits a JS event
+        │
+        ▼
+⑥  ControlCenter.onAction(({ id }) => ...) fires in JS
+```
+
+### Runtime — Toggle tap (e.g. "VPN")
+
+Two phases interleave: **rendering** (whenever Control Center asks the widget
+to draw itself) and **action** (when the user actually taps the toggle).
+
+```
+[ rendering ]
+①  Control Center asks the widget for its current state
+        │
+        ▼
+②  Provider.currentValue() runs
+        └── ControlStore.shared.getBool('vpnEnabled')
+              └── reads from App Group UserDefaults
+        │
+        ▼
+③  iOS draws the toggle with the returned value
+        └── on-icon vs off-icon, on-tint vs off-tint
+
+[ action ]
+①  user taps the toggle (currently OFF)
+        │
+        ▼
+②  iOS computes the new value (true) and injects into VpnToggleIntent.value
+        │
+        ▼
+③  VpnToggleIntent.perform() runs
+        │   ControlStore.shared.setBool('vpnEnabled', true)
+        │     └── write to App Group UserDefaults FIRST
+        │   ControlStore.shared.enqueueStateChange('vpnEnabled', true)
+        │     └── push event to queue + post Darwin notification
+        │   return .result()
+        │
+        ▼
+④  iOS re-runs the rendering flow above; toggle visually flips to ON
+        │
+        ▼
+⑤  (Week 5) Native Module drains the queue, emits a JS event
+        └── useControlState('vpnEnabled') hook updates → UI rerenders
+```
+
+---
+
+## API
+
+### `defineControls(map)`
+
+Build-time only. Declares your controls as a literal object (literal values
+only — no variables or function calls, so codegen never runs your code).
+
+```ts
+defineControls({
+  quickNote: { type: 'button', title: 'Quick Note', icon: 'square.and.pencil', deepLink?, tint?, description? },
+  vpnToggle: { type: 'toggle', title: 'VPN', icons: { on, off }, stateKey: 'vpnEnabled', tint?, description? },
+});
+```
+
+### `ControlCenter`
+
+Runtime singleton. Safe no-op off iOS 18.
+
+| Member | Description |
+| --- | --- |
+| `isAvailable(): boolean` | `true` only on iOS 18+ with the native module loaded |
+| `onAction(cb): () => void` | Fires when a **button** is tapped; `cb({ id, deepLink?, t })`. Returns an unsubscribe fn |
+| `onStateChange<T>(key, cb): () => void` | Fires when a **toggle**'s `stateKey` changes. Returns an unsubscribe fn |
+| `getState<T>(key): Promise<T \| null>` | Read App Group state (returns `null` off iOS) |
+| `setState<T>(key, value): Promise<void>` | Write App Group state; reloads Control Center so the toggle re-renders |
+
+### `useControlState<T>(stateKey)`
+
+React hook over a toggle's state — `const [value, setValue] = useControlState<boolean>('vpnEnabled')`.
+First render is synchronous from a cache (no `null` flicker on cold start), then
+stays in sync with both in-app `setValue` calls and Control Center taps.
+
+## Troubleshooting
+
+- **Control doesn't appear in Control Center** — it's iOS 18+ only; add the
+  control via Control Center's edit screen (`+`). Confirm `expo prebuild` /
+  `rn-control-center generate` ran and the widget target is in your Xcode project.
+- **Toggle doesn't sync with the app** — both targets must share the App Group.
+  The plugin/CLI generate the entitlement and inject `RNControlCenterAppGroup`
+  into the app `Info.plist`; if you changed the bundle id, re-run generation.
+- **`cannot find 'ControlStore'` or App Group errors when building** — re-run
+  generation after changing controls, then `pod install`.
+- **An icon renders blank** — the build prints a warning for unknown SF Symbol
+  names; check the spelling in SF Symbols.app.
+
+## Status
+
+Week 8 (May 2026) — **v0.1.0 release prep — docs, license, examples, slimmed package** ✅ &nbsp; · &nbsp; **138 tests passing**
+
+What Week 8 added:
+
+- [x] **Docs** — Requirements, Installation, full API reference, and Troubleshooting sections (above)
+- [x] **`examples/bare-rn`** — RN CLI example mirroring the Expo one (`rnControlCenter` config + `rn-control-center generate`)
+- [x] **MIT `LICENSE`** file (the `license` field had no accompanying file)
+- [x] **Slimmer tarball** — `files` no longer ships the source `.ts` that the built `lib/` already provides (≈108 kB → 71 kB packed); native sources, templates, CLI bin, and types are all still included
+- [x] **`v0.1.0`** — `npm run build` + `npm pack` verified; `prepublishOnly` runs typecheck + tests + build
+
+> Publishing to npm (`npm publish`) is the one remaining manual, irreversible step — run it when you're logged in (`npm whoami`).
+
+---
+
+## Earlier status
+
+Week 7 (May 2026) — **Expo example + xcodebuild compile E2E** ✅ — a real host-app compile caught three bugs the JS tests couldn't: a Swift module boundary (native module in the Pod couldn't see the app-generated `ControlStore` → fixed with a Pod-side [`ControlStoreRuntime`](ios/ControlStoreRuntime.swift) reading config from `Info.plist`), a non-existent `hasListeners` member, and a too-high podspec deployment target. Also fixed `package.json` `main`/`types`.
+
+Week 6 (May 2026) — **runtime hook polished + full SF Symbol set with build-time validation** ✅ &nbsp; · &nbsp; **136 tests passing**
+
+What works today:
+
+- [x] `defineControls({...})` types + `~200` curated SF Symbols literal union (autocomplete)
+- [x] **Full SF Symbol set** (5,359 names, generated from [symbolist](https://github.com/marcbouchenoire/symbolist), MIT) — build-time spell-check warns on typos like `lock.filll` without blocking the build
+- [x] **`useControlState` polish** — synchronous initial value from a JS cache seeded by a native `initialState` constant (no first-render `null` flicker on cold start); programmatic `setState` calls `ControlCenter.shared.reloadAllControls()` so the Control Center toggle re-renders immediately
+- [x] Babel AST parser with literal-only policy and line-aware errors
+- [x] Handlebars templates for **Button** + **Toggle** controls, intents, and `ControlStore.swift`
+- [x] `generateNativeFiles()` — emits 8 Swift/plist/entitlement files tagged with target membership
+- [x] `wireXcodeProject()` — mutates `project.pbxproj` to add the widget target, link frameworks, register the synced folder + ExceptionSets, and apply build settings on both targets
+- [x] **Expo Config Plugin** (`plugin/index.ts`) wires the entire pipeline into `expo prebuild`
+- [x] **Standalone CLI** (`npx rn-control-center generate`) runs the same pipeline for bare RN CLI projects
+- [x] **End-to-end build validated:** in a real Expo app, `expo prebuild` produces a project that builds with `xcodebuild`, the control shows up in iOS Control Center, and tapping it opens the main app — the failure mode that bacons-based setups hit because they couldn't put the AppIntent in both targets is solved here by the ExceptionSet flow
+- [x] **Native Module** (`ios/RNControlCenter.swift` + `.mm`) — Darwin notification observer with `Unmanaged` pointer trick, cold-start queue drain, App Group `UserDefaults` get/set exposed to JS via Promise. Legacy Bridge (`RCT_EXTERN_MODULE`); TurboModule migration planned for v0.2
+- [x] **`.podspec`** — CocoaPods integration; library autolinks into a consumer RN app's `pod install`
+- [x] **JS wrapper** (`src/ControlCenter.ts`) — `NativeEventEmitter` over the native module; `onAction` / `onStateChange` event subscriptions, `getState` / `setState` Promise-based; safe no-op on Android and pre-iOS-18
+
+---
+
+## Roadmap
+
+| Week | Milestone | Status |
+| ---- | --------- | ------ |
+| 1 | Scaffold + AST parser + Button Swift templates | ✅ |
+| 2 | Toggle template + ControlStore runtime + Info.plist / entitlement generation | ✅ |
+| 3 | pbxproj target wiring (target add, framework link, membership, build settings) | ✅ |
+| 4 | Expo Config Plugin + standalone CLI (`rn-control-center generate`) | ✅ |
+| 5 | Native Module (Darwin notifications + App Group UserDefaults) | ✅ |
+| 6 | Full SF Symbol set + validation + `useControlState` runtime (cache + reload) | ✅ |
+| 7 | Expo example app + xcodebuild compile E2E (host app + extension link on real SDK) | ✅ |
+| 8 | Documentation + RN CLI example + v0.1.0 release prep (publish = manual step) | ✅ |
+
+v0.2+: Android Quick Settings Tiles for a unified cross-platform API, Lock Screen and Action Button control targets, dynamic intents.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/alstjd8826/react-native-control-center.git
+cd react-native-control-center
+npm install --legacy-peer-deps
+
+npm run typecheck   # tsc --noEmit
+npm test            # jest, 138 tests
+```
+
+The repo is structured as a publishable RN library plus the tooling that backs it:
+
+```
+src/      → public API shipped to consumers
+core/     → parser + codegen (shared by Expo plugin and CLI)
+plugin/   → Expo Config Plugin entry point
+cli/      → standalone `rn-control-center` binary
+ios/      → native module sources
+scripts/  → tooling (e.g. gen-sf-symbols.mjs regenerates the symbol list)
+```
+
+---
+
+## Design notes
+
+- **Literal-only configs.** `defineControls({...})` must contain literal values only; variable references and function calls are rejected at parse time. This lets codegen run without ever executing user code.
+- **Independent of `@bacons/apple-targets`.** Bacons is a great general-purpose target plugin, but was tripped up by `@expo/prebuild-config` path changes in Expo SDK 54 during early prototyping. This library talks to `pbxproj` directly through the `xcode` npm package for a narrower, more stable surface.
+- **App Group–backed state.** Toggle state lives in a suite UserDefaults shared between the main app and the widget extension; the library generates the entitlement and provisions a sensible default group ID.
+
+---
+
+## License
+
+MIT

package/app.plugin.js

@@ -0,0 +1,14 @@
+// Expo가 plugins 배열에서 패키지 이름만 봤을 때 이 파일을 찾도록.
+// 빌드된 lib/ 결과물이 있으면 거길 보고, 없으면 src를 ts-node 처리.
+const path = require('path');
+
+let plugin;
+try {
+  plugin = require(path.join(__dirname, 'lib', 'commonjs', 'plugin')).default;
+} catch {
+  // 로컬 개발 (라이브러리 빌드 전) — TS 직접 실행
+  require('ts-node/register');
+  plugin = require(path.join(__dirname, 'plugin', 'index')).default;
+}
+
+module.exports = plugin;

package/cli/bin/rn-control-center.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/* eslint-disable @typescript-eslint/no-var-requires */
+
+const path = require('path');
+
+let runGenerate;
+try {
+  // production: 빌드된 lib에서 로드
+  ({ runGenerate } = require(path.join(__dirname, '..', '..', 'lib', 'commonjs', 'cli', 'runGenerate')));
+} catch {
+  // 로컬 개발: TS 직접 실행
+  require('ts-node/register');
+  ({ runGenerate } = require(path.join(__dirname, '..', 'runGenerate')));
+}
+
+const command = process.argv[2];
+
+if (!command || command === 'help' || command === '--help') {
+  console.log(
+    [
+      'Usage: rn-control-center <command>',
+      '',
+      'Commands:',
+      '  generate    Generate widget extension files into ios/ and modify pbxproj',
+      '',
+      'Reads configuration from your project package.json:',
+      '  {',
+      '    "rnControlCenter": {',
+      '      "controls": "./src/controls.ts",',
+      '      "urlScheme": "myapp"',
+      '    }',
+      '  }',
+    ].join('\n')
+  );
+  process.exit(0);
+}
+
+if (command === 'generate') {
+  try {
+    const result = runGenerate();
+    console.log(`✓ Wrote ${result.filesWritten.length} files`);
+    console.log(`✓ Updated ${result.pbxprojPath}`);
+    console.log('  Widget target:  ' + result.widgetTargetUuid);
+    console.log('  Main app target:' + result.mainAppTargetUuid);
+  } catch (err) {
+    console.error(err.message ?? err);
+    process.exit(1);
+  }
+} else {
+  console.error(`Unknown command: ${command}`);
+  process.exit(2);
+}

package/ios/ControlStoreRuntime.swift

@@ -0,0 +1,81 @@
+import Foundation
+
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  ControlStoreRuntime.swift   (라이브러리가 Pod으로 배송 — 메인 앱 쪽)
+//
+//  왜 이게 따로 있나:
+//   위젯 익스텐션에는 codegen이 만든 `ControlStore.swift`가 들어간다. 하지만 그
+//   파일은 "앱/위젯 타겟"에 속하고, Native Module(RNControlCenter)은 별도의
+//   "Pod 모듈"로 컴파일되기 때문에 서로의 클래스를 볼 수 없다
+//   (Swift 모듈 경계). 그래서 메인 앱 쪽에서 쓸 런타임 스토어를 라이브러리가
+//   직접 배송한다.
+//
+//  생성된 ControlStore와 "같은 사물함"을 바라봐야 하므로:
+//   • App Group ID  → 메인 앱 Info.plist의 "RNControlCenterAppGroup" 에서 읽음
+//                     (Expo 플러그인 / CLI가 codegen과 동일한 값으로 주입)
+//   • Darwin 이름   → "<appGroup>.event"  (생성 코드와 동일 규칙)
+//   • 큐 키         → "__rncc.actionQueue" / "__rncc.stateChangeQueue" (동일 상수)
+//   • stateKeys     → Info.plist "RNControlCenterStateKeys" (snapshot 정제용)
+// ─────────────────────────────────────────────────────────────────────────
+
+public final class ControlStoreRuntime {
+    public static let shared = ControlStoreRuntime()
+
+    // 생성된 ControlStore와 반드시 일치해야 하는 큐 키.
+    private static let actionQueueKey = "__rncc.actionQueue"
+    private static let stateChangeQueueKey = "__rncc.stateChangeQueue"
+
+    public let appGroupId: String
+    public let darwinNotificationName: String
+    public let stateKeys: [String]
+
+    private let defaults: UserDefaults
+
+    private init() {
+        let info = Bundle.main.infoDictionary
+        let group = (info?["RNControlCenterAppGroup"] as? String) ?? ""
+        self.appGroupId = group
+        self.stateKeys = (info?["RNControlCenterStateKeys"] as? [String]) ?? []
+        self.darwinNotificationName = group.isEmpty ? "rncc.event" : "\(group).event"
+
+        // App Group이 비어있거나 entitlement 미설정이면 표준 defaults로 폴백.
+        // (위젯이 안 보이는 환경 등 — 라이브러리가 크래시 없이 no-op 되도록)
+        self.defaults = UserDefaults(suiteName: group) ?? .standard
+    }
+
+    // ─── Toggle 상태 R/W (useControlState 훅이 사용) ──────────────────────
+
+    public func getBool(_ key: String) -> Bool {
+        return defaults.bool(forKey: key)
+    }
+
+    public func setBool(_ key: String, value: Bool) {
+        defaults.set(value, forKey: key)
+    }
+
+    /// 선언된 stateKey들의 현재 값 스냅샷. constantsToExport(initialState)로 전달돼
+    /// JS 캐시를 콜드 스타트 시점에 채운다.
+    public func snapshot() -> [String: Any] {
+        var out: [String: Any] = [:]
+        for key in stateKeys {
+            if let value = defaults.object(forKey: key) {
+                out[key] = value
+            }
+        }
+        return out
+    }
+
+    // ─── 이벤트 큐 drain (위젯이 enqueue → 앱이 dequeue) ──────────────────
+
+    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
+    }
+}

package/ios/RNControlCenter.mm

@@ -0,0 +1,28 @@
+// ─────────────────────────────────────────────────────────────────────────
+//  📄  RNControlCenter.mm
+//  Objective-C 브릿지 — Swift로 작성한 RNControlCenter 클래스를
+//  React Native의 Legacy Bridge에 "Native Module"로 등록한다.
+//
+//  .swift 파일이 클래스를 ObjC 런타임에 "노출"한다면,
+//  이 파일은 그것을 RN 브릿지에 "신청"하는 서류 역할.
+// ─────────────────────────────────────────────────────────────────────────
+
+#import <React/RCTBridgeModule.h>
+#import <React/RCTEventEmitter.h>
+
+// 클래스 등록 — Swift의 @objc(RNControlCenter)와 이름이 일치해야 함.
+// 두 번째 인자 RCTEventEmitter는 부모 클래스를 RN에게 알려주는 정보.
+@interface RCT_EXTERN_MODULE(RNControlCenter, RCTEventEmitter)
+
+// 메서드 등록 — Swift 쪽 @objc func 시그니처와 1:1 매칭.
+
+RCT_EXTERN_METHOD(getState:(NSString *)key
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+RCT_EXTERN_METHOD(setState:(NSString *)key
+                     value:(BOOL)value
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject)
+
+@end