feat: add dev mode for previewing local paywalls

CHANGELOG.md

@@ -8,6 +8,8 @@ The changelog for `SuperwallKit`. Also see the [releases](https://github.com/sup
 
 - Adds `grantedEntitlements` so you can grant entitlements from your own backend, which the SDK merges with device and web entitlements.
 - Changes `$subscriptionStatus` from a `@Published` publisher to an `AnyPublisher`. Subscribing to it works as before, but it can no longer be the target of `assign(to:)`.
+- Dev mode now presents a locally served paywall the way its `config.ts` says: presentation style, feature gating, intro offer eligibility, scrolling and background colours come from your local code instead of the last pushed version, so changing them is visible without a push. Settings `config.ts` cannot express, and any it leaves out, still come from the published paywall. Needs a `superwall dev` server new enough to send them.
+- Adds `SuperwallOptions.devServer` for development builds: with a `superwall dev` server running, paywalls render from your live, local paywall code while configuration, placements, audience evaluation and assignment stay real. Use `.default` on a simulator, which finds the dev server on localhost automatically; on a physical device use `.url(...)` with the Device URL `superwall dev` prints. The dev server also activates test mode, disables preloading, and skips the test mode intro sheet.
 
 ### Fixes
 

Examples/Advanced/Advanced/Info.plist

@@ -17,7 +17,9 @@
 	</array>
 	<key>NSAppTransportSecurity</key>
 	<dict>
-		<key>NSAllowsArbitraryLoads</key>
+		<key>NSAllowsArbitraryLoadsInWebContent</key>
+		<true/>
+		<key>NSAllowsLocalNetworking</key>
 		<true/>
 	</dict>
 	<key>UIAppFonts</key>

Examples/Basic/Basic/Info.plist

@@ -13,6 +13,13 @@
 			</array>
 		</dict>
 	</array>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoadsInWebContent</key>
+		<true/>
+		<key>NSAllowsLocalNetworking</key>
+		<true/>
+	</dict>
 	<key>UIAppFonts</key>
 	<array>
 		<string>Rubik-Regular.ttf</string>

Sources/SuperwallKit/Config/ConfigManager.swift

@@ -439,8 +439,12 @@ class ConfigManager {
     let shouldShowTestModeAlert = isFirstTime || testModeJustActivated
     if shouldShowTestModeAlert,
       testModeManager.isTestMode,
-      let reason = testModeManager.testModeReason {
-      await presentTestModeModal(reason: reason, config: config)
+      testModeManager.testModeReason != nil {
+      if DevMode.isActive(options) {
+        await applyDefaultTestModeState(testModeManager: testModeManager)
+      } else if let reason = testModeManager.testModeReason {
+        await presentTestModeModal(reason: reason, config: config)
+      }
     }
   }
 
@@ -557,7 +561,10 @@ class ConfigManager {
   ///
   /// A developer can disable preloading of paywalls by setting ``SuperwallOptions/shouldPreloadPaywalls``.
   private func preloadPaywalls() async {
-    guard Superwall.shared.options.paywalls.shouldPreload else {
+    guard
+      Superwall.shared.options.paywalls.shouldPreload,
+      !DevMode.isActive(Superwall.shared.options)
+    else {
       return
     }
     await preloadAllPaywalls()
@@ -723,6 +730,24 @@ class ConfigManager {
     }
   }
 
+  /// Seeds the state the test mode modal would otherwise collect, without
+  /// presenting it. Used when a dev server drives the SDK: every entitlement
+  /// starts inactive so paywalls present, and purchases flip them for real.
+  @MainActor
+  private func applyDefaultTestModeState(testModeManager: TestModeManager) async {
+    testModeManager.setEntitlements([])
+    let testModeCustomerInfo = CustomerInfo(
+      subscriptions: [],
+      nonSubscriptions: [],
+      entitlements: []
+    )
+    testModeManager.overriddenCustomerInfo = testModeCustomerInfo
+    Superwall.shared.customerInfo = testModeCustomerInfo
+    testModeManager.overriddenSubscriptionStatus = .inactive
+    Superwall.shared.setSubscriptionStatus(assigned: .inactive)
+    storage.save(false, forType: IsTestModeActiveSubscription.self)
+  }
+
   @MainActor
   private func presentTestModeModal(reason: TestModeReason, config: Config) async {
     guard

Sources/SuperwallKit/Config/Options/SuperwallOptions.swift

@@ -388,6 +388,76 @@ public final class SuperwallOptions: NSObject, Encodable {
   /// - `.always`: Test mode is always activated, regardless of configuration.
   public var testModeBehavior: TestModeBehavior = .automatic
 
+  /// A running `superwall dev` server for ``SuperwallOptions/devServer`` to connect to.
+  public enum DevServer: Equatable {
+    /// Finds the dev server on `localhost` ports 6100–6104, which reaches a server
+    /// running on the same machine from a simulator.
+    case `default`
+
+    /// The dev server at an exact address — the `Device` URL's origin that
+    /// `superwall dev` prints, e.g. `http://192.168.1.10:6100`. Use this on a
+    /// physical device, which can't reach your machine via `localhost`.
+    case url(URL)
+  }
+
+  /// Connects this SDK instance to a running `superwall dev` server, for development builds only.
+  ///
+  /// Paywalls with a local counterpart on the dev server then render from your live, local
+  /// paywall code instead of their published versions, while configuration, placements,
+  /// audience evaluation, assignment and the enforcement of feature gating all stay real.
+  /// Paywalls without a local counterpart still load their published versions.
+  ///
+  /// What the local surface owns is what it renders and the settings its `config.ts`
+  /// declares: content, products, presentation style, feature gating, intro offer
+  /// eligibility, scrolling and background colours all come from your local code, so
+  /// changing them shows on the next presentation without a push. What `config.ts`
+  /// cannot express — surveys, computed properties — comes from the published paywall
+  /// the surface stands in for, and so does any setting your `config.ts` leaves out.
+  ///
+  /// A dev server older than this SDK sends no settings at all, in which case every
+  /// setting comes from the published paywall.
+  ///
+  /// Two exceptions. Local notifications are always the local paywall's: the published
+  /// ones are ignored and the ones your `config.ts` declares fire without a push, because
+  /// they reach the SDK from the paywall itself rather than from the dashboard. And the
+  /// on-device cache stays off however either side configures it, so a page you are
+  /// editing is never served from the web view's cache.
+  ///
+  /// Use ``DevServer/default`` on a simulator; on a physical device use ``DevServer/url(_:)``
+  /// with the `Device` URL that `superwall dev` prints. Defaults to `nil`: no dev server.
+  ///
+  /// The dev server also activates test mode (simulated purchases, product data from the
+  /// dashboard), disables paywall preloading, and skips the test mode intro sheet.
+  ///
+  /// The host app must allow local networking in its `Info.plist`
+  /// (`NSAppTransportSecurity` → `NSAllowsLocalNetworking` and
+  /// `NSAllowsArbitraryLoadsInWebContent`).
+  @nonobjc public var devServer: DevServer?
+
+  /// Objective-C only: connects to a `superwall dev` server found on `localhost`.
+  @available(swift, obsoleted: 1.0)
+  public func enableDevServer() {
+    devServer = .default
+  }
+
+  /// Objective-C only: connects to the `superwall dev` server at this address.
+  @available(swift, obsoleted: 1.0)
+  public func enableDevServer(url: URL) {
+    devServer = .url(url)
+  }
+
+  var isDevServerEnabled: Bool {
+    return devServer != nil
+  }
+
+  /// Where ``devServer``'s ``DevServer/url(_:)`` case points, if that's what is set.
+  var devServerURL: URL? {
+    if case .url(let url) = devServer {
+      return url
+    }
+    return nil
+  }
+
   /// Determines the number of times the SDK will attempt to get the Superwall configuration after a network
   /// failure before it times out. Defaults to 6.
   ///

Sources/SuperwallKit/Debug/DebugManager.swift

@@ -12,6 +12,10 @@ final class DebugManager {
   @MainActor var viewController: DebugViewController?
 	var isDebuggerLaunched = false
 
+  /// The surfaces a running `superwall dev` server exposes, and where it lives.
+  /// Set when the debugger is opened from a `superwall_dev` deep link.
+  @MainActor var devServer: (base: URL, surfaces: [DevServerSurface])?
+
   private unowned let storage: Storage
   private unowned let factory: ViewControllerFactory
   struct DeepLinkOutcome {
@@ -68,38 +72,48 @@ final class DebugManager {
   ///
   /// Remember to add your URL scheme in settings for QR code scanning to work.
   @MainActor
-  func launchDebugger(withPaywallId paywallDatabaseId: String? = nil) async {
+  func launchDebugger(
+    withPaywallId paywallDatabaseId: String? = nil,
+    devSurfaceId: String? = nil
+  ) async {
     if Superwall.shared.isPaywallPresented {
       await Superwall.shared.dismiss()
-      await launchDebugger(withPaywallId: paywallDatabaseId)
+      await launchDebugger(withPaywallId: paywallDatabaseId, devSurfaceId: devSurfaceId)
 		} else {
 			if viewController == nil {
         let milliseconds = 200
         let nanoseconds = UInt64(milliseconds * 1_000_000)
         try? await Task.sleep(nanoseconds: nanoseconds)
-        await presentDebugger(withPaywallId: paywallDatabaseId)
+        await presentDebugger(withPaywallId: paywallDatabaseId, devSurfaceId: devSurfaceId)
 			} else {
         await closeDebugger(animated: true)
-        await launchDebugger(withPaywallId: paywallDatabaseId)
+        await launchDebugger(withPaywallId: paywallDatabaseId, devSurfaceId: devSurfaceId)
 			}
 		}
 	}
 
   @MainActor
-	func presentDebugger(withPaywallId paywallDatabaseId: String? = nil) async {
+	func presentDebugger(
+    withPaywallId paywallDatabaseId: String? = nil,
+    devSurfaceId: String? = nil
+  ) async {
 		isDebuggerLaunched = true
 		if let viewController = viewController {
       if viewController.isBeingPresented {
         return
       }
 			viewController.paywallDatabaseId = paywallDatabaseId
+      viewController.devServer = devServer
+      viewController.selectDevSurface(id: devSurfaceId)
 			await viewController.loadPreview()
 			await UIViewController.topMostViewController?.present(
         viewController,
         animated: true
       )
 		} else {
       let viewController = factory.makeDebugViewController(withDatabaseId: paywallDatabaseId)
+      viewController.devServer = devServer
+      viewController.selectDevSurface(id: devSurfaceId)
 			UIViewController.topMostViewController?.present(
         viewController,
         animated: true,