@sigx/lynx-dev-client 0.1.0

package/ios/Sources/SigxDevClient/DevMenuView.swift

@@ -0,0 +1,133 @@
+import SwiftUI
+import UIKit
+
+/// Action callbacks the dev menu invokes. Mirrors the shape of Android's
+/// `DevMenuActions` so iOS templates wire up the same set of buttons.
+public struct DevMenuActions {
+    public let onReload: () -> Void
+    public let onChangeUrl: (String) -> Void
+    public let onCopyUrl: () -> Void
+    /// Sandbox-host hook: when non-nil, the dev menu shows a "Back to Home"
+    /// button that disconnects from the current bundle and returns to
+    /// `DevHomeScreen` (so the user can pick a different URL). Nil for apps
+    /// with a baked bundle — there's no home to return to.
+    public let onDisconnect: (() -> Void)?
+    public let currentUrl: String
+    public let nativeModules: [String]
+
+    public init(
+        onReload: @escaping () -> Void,
+        onChangeUrl: @escaping (String) -> Void,
+        onCopyUrl: @escaping () -> Void,
+        onDisconnect: (() -> Void)? = nil,
+        currentUrl: String,
+        nativeModules: [String] = []
+    ) {
+        self.onReload = onReload
+        self.onChangeUrl = onChangeUrl
+        self.onCopyUrl = onCopyUrl
+        self.onDisconnect = onDisconnect
+        self.currentUrl = currentUrl
+        self.nativeModules = nativeModules
+    }
+}
+
+/// SwiftUI dev menu sheet. Present with `.sheet(isPresented:)`, then bind the
+/// dismissal back through `isPresented`.
+public struct DevMenuView: View {
+    @Binding var isPresented: Bool
+    let actions: DevMenuActions
+
+    @State private var newUrl: String = ""
+    @State private var showUrlInput: Bool = false
+    @State private var copyToast: String?
+
+    public init(isPresented: Binding<Bool>, actions: DevMenuActions) {
+        self._isPresented = isPresented
+        self.actions = actions
+    }
+
+    public var body: some View {
+        NavigationView {
+            List {
+                Section {
+                    Button {
+                        actions.onReload()
+                        isPresented = false
+                    } label: {
+                        Label("Reload", systemImage: "arrow.clockwise")
+                    }
+
+                    DisclosureGroup(isExpanded: $showUrlInput) {
+                        HStack {
+                            TextField("Server URL", text: $newUrl)
+                                .keyboardType(.URL)
+                                .textInputAutocapitalization(.never)
+                                .disableAutocorrection(true)
+                                .submitLabel(.go)
+                                .onSubmit { submitUrl() }
+                            Button("Go") { submitUrl() }
+                                .buttonStyle(.borderedProminent)
+                                .disabled(newUrl.isEmpty)
+                        }
+                    } label: {
+                        VStack(alignment: .leading, spacing: 2) {
+                            Label("Change Dev Server", systemImage: "pencil")
+                            if !showUrlInput {
+                                Text(actions.currentUrl)
+                                    .font(.caption)
+                                    .foregroundColor(.secondary)
+                                    .padding(.leading, 28)
+                            }
+                        }
+                    }
+
+                    Button {
+                        actions.onCopyUrl()
+                        copyToast = "URL copied"
+                        DispatchQueue.main.asyncAfter(deadline: .now() + 1.2) {
+                            copyToast = nil
+                            isPresented = false
+                        }
+                    } label: {
+                        Label(copyToast ?? "Copy URL", systemImage: "doc.on.doc")
+                    }
+
+                    if let onDisconnect = actions.onDisconnect {
+                        Button(role: .destructive) {
+                            isPresented = false
+                            onDisconnect()
+                        } label: {
+                            Label("Back to Home", systemImage: "house")
+                        }
+                    }
+                }
+
+                if !actions.nativeModules.isEmpty {
+                    Section("Native Modules (\(actions.nativeModules.count))") {
+                        ForEach(actions.nativeModules, id: \.self) { name in
+                            Text(name)
+                                .font(.system(.caption, design: .monospaced))
+                                .foregroundColor(.secondary)
+                        }
+                    }
+                }
+            }
+            .navigationTitle("sigx Dev Menu")
+            .navigationBarTitleDisplayMode(.inline)
+            .toolbar {
+                ToolbarItem(placement: .navigationBarTrailing) {
+                    Button("Close") { isPresented = false }
+                }
+            }
+            .onAppear { newUrl = actions.currentUrl }
+        }
+    }
+
+    private func submitUrl() {
+        guard !newUrl.isEmpty else { return }
+        actions.onChangeUrl(newUrl)
+        showUrlInput = false
+        isPresented = false
+    }
+}

package/ios/Sources/SigxDevClient/DevQRScanner.swift

@@ -0,0 +1,165 @@
+import SwiftUI
+import AVFoundation
+
+/// Camera-driven QR scanner for the dev home screen. Reports scanned codes
+/// back via `onCodeScanned`. Caller is responsible for dismissing whatever
+/// container presented this view.
+public struct DevQRScanner: View {
+    let onCodeScanned: (String) -> Void
+
+    @State private var cameraPermissionGranted = false
+    @State private var showPermissionAlert = false
+
+    public init(onCodeScanned: @escaping (String) -> Void) {
+        self.onCodeScanned = onCodeScanned
+    }
+
+    public var body: some View {
+        ZStack {
+            if cameraPermissionGranted {
+                DevQRCameraPreview(onCodeScanned: onCodeScanned)
+                    .ignoresSafeArea()
+
+                VStack {
+                    Spacer()
+                    Text("Point camera at QR code from dev server")
+                        .padding()
+                        .background(.regularMaterial, in: RoundedRectangle(cornerRadius: 8))
+                        .padding(.bottom, 48)
+                }
+            } else {
+                VStack(spacing: 16) {
+                    Image(systemName: "camera.fill")
+                        .font(.largeTitle)
+                        .foregroundColor(.secondary)
+                    Text("Camera permission is required to scan QR codes.")
+                        .multilineTextAlignment(.center)
+                        .foregroundColor(.secondary)
+                    Button("Grant Permission") {
+                        requestCameraPermission()
+                    }
+                    .buttonStyle(.borderedProminent)
+                }
+                .padding()
+            }
+        }
+        .navigationTitle("Scan QR Code")
+        .navigationBarTitleDisplayMode(.inline)
+        .onAppear {
+            checkCameraPermission()
+        }
+        .alert("Camera Permission Required", isPresented: $showPermissionAlert) {
+            Button("Open Settings") {
+                if let url = URL(string: UIApplication.openSettingsURLString) {
+                    UIApplication.shared.open(url)
+                }
+            }
+            Button("Cancel", role: .cancel) {}
+        } message: {
+            Text("Please enable camera access in Settings to scan QR codes.")
+        }
+    }
+
+    private func checkCameraPermission() {
+        switch AVCaptureDevice.authorizationStatus(for: .video) {
+        case .authorized:
+            cameraPermissionGranted = true
+        case .notDetermined:
+            requestCameraPermission()
+        default:
+            showPermissionAlert = true
+        }
+    }
+
+    private func requestCameraPermission() {
+        AVCaptureDevice.requestAccess(for: .video) { granted in
+            DispatchQueue.main.async {
+                cameraPermissionGranted = granted
+                if !granted {
+                    showPermissionAlert = true
+                }
+            }
+        }
+    }
+}
+
+private struct DevQRCameraPreview: UIViewControllerRepresentable {
+    let onCodeScanned: (String) -> Void
+
+    func makeUIViewController(context: Context) -> DevQRScannerViewController {
+        let vc = DevQRScannerViewController()
+        vc.onCodeScanned = onCodeScanned
+        return vc
+    }
+
+    func updateUIViewController(_ uiViewController: DevQRScannerViewController, context: Context) {}
+}
+
+private final class DevQRScannerViewController: UIViewController, AVCaptureMetadataOutputObjectsDelegate {
+    var onCodeScanned: ((String) -> Void)?
+
+    private var captureSession: AVCaptureSession?
+    private var previewLayer: AVCaptureVideoPreviewLayer?
+    private var hasScanned = false
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        setupCamera()
+    }
+
+    override func viewDidLayoutSubviews() {
+        super.viewDidLayoutSubviews()
+        previewLayer?.frame = view.layer.bounds
+    }
+
+    private func setupCamera() {
+        let session = AVCaptureSession()
+
+        guard let device = AVCaptureDevice.default(for: .video),
+              let input = try? AVCaptureDeviceInput(device: device) else {
+            return
+        }
+
+        if session.canAddInput(input) {
+            session.addInput(input)
+        }
+
+        let output = AVCaptureMetadataOutput()
+        if session.canAddOutput(output) {
+            session.addOutput(output)
+            output.setMetadataObjectsDelegate(self, queue: DispatchQueue.main)
+            output.metadataObjectTypes = [.qr]
+        }
+
+        let previewLayer = AVCaptureVideoPreviewLayer(session: session)
+        previewLayer.frame = view.layer.bounds
+        previewLayer.videoGravity = .resizeAspectFill
+        view.layer.addSublayer(previewLayer)
+        self.previewLayer = previewLayer
+
+        self.captureSession = session
+        DispatchQueue.global(qos: .background).async {
+            session.startRunning()
+        }
+    }
+
+    func metadataOutput(
+        _ output: AVCaptureMetadataOutput,
+        didOutput metadataObjects: [AVMetadataObject],
+        from connection: AVCaptureConnection
+    ) {
+        guard !hasScanned,
+              let metadataObject = metadataObjects.first as? AVMetadataMachineReadableCodeObject,
+              let value = metadataObject.stringValue else {
+            return
+        }
+
+        hasScanned = true
+        captureSession?.stopRunning()
+
+        let generator = UINotificationFeedbackGenerator()
+        generator.notificationOccurred(.success)
+
+        onCodeScanned?(value)
+    }
+}

package/ios/Sources/SigxDevClient/DevTemplateProvider.swift

@@ -0,0 +1,68 @@
+import Foundation
+import Lynx
+
+/// Loads Lynx bundles from URLs (dev server) or local assets.
+/// Implements LynxTemplateProvider protocol.
+class DevTemplateProvider: NSObject, LynxTemplateProvider {
+
+    func loadTemplate(withUrl url: String!, onComplete callback: ((Any?, Error?) -> Void)!) {
+        guard let callback = callback else { return }
+
+        if url.hasPrefix("http://") || url.hasPrefix("https://") {
+            loadFromURL(url, callback: callback)
+        } else {
+            loadFromAssets(url, callback: callback)
+        }
+    }
+
+    private func loadFromURL(_ urlString: String, callback: @escaping (Any?, Error?) -> Void) {
+        guard let url = URL(string: urlString) else {
+            let error = NSError(
+                domain: "com.sigx.devclient",
+                code: 400,
+                userInfo: [NSLocalizedDescriptionKey: "Invalid URL: \(urlString)"]
+            )
+            callback(nil, error)
+            return
+        }
+
+        var request = URLRequest(url: url)
+        request.timeoutInterval = 30
+
+        URLSession.shared.dataTask(with: request) { data, response, error in
+            if let error = error {
+                callback(nil, error)
+                return
+            }
+            guard let data = data else {
+                let error = NSError(
+                    domain: "com.sigx.devclient",
+                    code: 404,
+                    userInfo: [NSLocalizedDescriptionKey: "No data received from \(urlString)"]
+                )
+                callback(nil, error)
+                return
+            }
+            callback(data, nil)
+        }.resume()
+    }
+
+    private func loadFromAssets(_ name: String, callback: @escaping (Any?, Error?) -> Void) {
+        guard let path = Bundle.main.path(forResource: name, ofType: nil) else {
+            let error = NSError(
+                domain: "com.sigx.devclient",
+                code: 404,
+                userInfo: [NSLocalizedDescriptionKey: "Asset not found: \(name)"]
+            )
+            callback(nil, error)
+            return
+        }
+
+        do {
+            let data = try Data(contentsOf: URL(fileURLWithPath: path))
+            callback(data, nil)
+        } catch {
+            callback(nil, error)
+        }
+    }
+}

package/ios/Sources/SigxDevClient/DevTemplateResourceFetcher.swift

@@ -0,0 +1,73 @@
+import Foundation
+import Lynx
+
+/// Handles template and HMR hot-update fetching for LynxView.
+/// Required for HMR — the template provider only handles initial loads.
+class DevTemplateResourceFetcher: NSObject, LynxTemplateResourceFetcher {
+
+    private let session: URLSession = {
+        let config = URLSessionConfiguration.default
+        config.timeoutIntervalForRequest = 30
+        config.timeoutIntervalForResource = 60
+        return URLSession(configuration: config)
+    }()
+
+    func fetchTemplate(
+        _ request: LynxResourceRequest,
+        onComplete callback: @escaping (LynxTemplateResource?, Error?) -> Void
+    ) {
+        let url = request.url ?? ""
+
+        if url.hasPrefix("file://") || (!url.hasPrefix("http://") && !url.hasPrefix("https://")) {
+            fetchFromAssets(url.replacingOccurrences(of: "file://", with: ""), callback: callback)
+            return
+        }
+
+        guard let requestURL = URL(string: url) else {
+            callback(nil, NSError(domain: "com.sigx.devclient", code: 400,
+                                  userInfo: [NSLocalizedDescriptionKey: "Invalid URL: \(url)"]))
+            return
+        }
+
+        session.dataTask(with: requestURL) { data, response, error in
+            if let error = error {
+                callback(nil, error)
+                return
+            }
+            guard let data = data else {
+                callback(nil, NSError(domain: "com.sigx.devclient", code: 404,
+                                      userInfo: [NSLocalizedDescriptionKey: "No data received"]))
+                return
+            }
+            let resource = LynxTemplateResource(nsData: data)
+            callback(resource, nil)
+        }.resume()
+    }
+
+    func fetchSSRData(
+        _ request: LynxResourceRequest,
+        onComplete callback: @escaping (Data?, Error?) -> Void
+    ) {
+        // SSR not used in dev mode; return nil
+        callback(nil, nil)
+    }
+
+    private func fetchFromAssets(
+        _ path: String,
+        callback: @escaping (LynxTemplateResource?, Error?) -> Void
+    ) {
+        guard let bundlePath = Bundle.main.path(forResource: path, ofType: nil) else {
+            callback(nil, NSError(domain: "com.sigx.devclient", code: 404,
+                                  userInfo: [NSLocalizedDescriptionKey: "Asset not found: \(path)"]))
+            return
+        }
+
+        do {
+            let data = try Data(contentsOf: URL(fileURLWithPath: bundlePath))
+            let resource = LynxTemplateResource(nsData: data)
+            callback(resource, nil)
+        } catch {
+            callback(nil, error)
+        }
+    }
+}

package/ios/Sources/SigxDevClient/ShakeDetector.swift

@@ -0,0 +1,60 @@
+import UIKit
+import SwiftUI
+import ObjectiveC.runtime
+
+public extension Notification.Name {
+    static let sigxDeviceDidShake = Notification.Name("sigxDeviceDidShake")
+}
+
+/// Global shake detector for SwiftUI apps.
+///
+/// SwiftUI doesn't expose `UIWindow.motionEnded(_:with:)`, and Swift extensions
+/// can't `override` inherited Obj-C methods. So we install a runtime swizzle:
+/// `class_replaceMethod` adds our own `motionEnded:withEvent:` IMP onto
+/// `UIWindow`, and our IMP forwards to the original `UIResponder` impl before
+/// posting `.sigxDeviceDidShake` on the default notification center.
+///
+/// Idempotent — `enable()` is safe to call repeatedly; the swizzle runs once
+/// thanks to Swift static-let initialisation semantics.
+public enum SigxShakeDetector {
+    private static let installed: Void = {
+        installSwizzle()
+    }()
+
+    public static func enable() {
+        _ = installed
+    }
+
+    private static func installSwizzle() {
+        let cls: AnyClass = UIWindow.self
+        let selector = #selector(UIResponder.motionEnded(_:with:))
+        guard let method = class_getInstanceMethod(cls, selector) else { return }
+
+        let originalIMP = method_getImplementation(method)
+        let typeEncoding = method_getTypeEncoding(method)
+
+        typealias Function = @convention(c) (UIWindow, Selector, UIEvent.EventSubtype, UIEvent?) -> Void
+        let originalFunc = unsafeBitCast(originalIMP, to: Function.self)
+
+        let block: @convention(block) (UIWindow, UIEvent.EventSubtype, UIEvent?) -> Void = { window, motion, event in
+            originalFunc(window, selector, motion, event)
+            if motion == .motionShake {
+                NotificationCenter.default.post(name: .sigxDeviceDidShake, object: nil)
+            }
+        }
+        let newIMP = imp_implementationWithBlock(block)
+        class_replaceMethod(cls, selector, newIMP, typeEncoding)
+    }
+}
+
+public extension View {
+    /// Triggers `action` when the device is shaken. Installs a global UIWindow
+    /// `motionEnded:` swizzle on first use so the event fires regardless of
+    /// first-responder state.
+    func onShake(perform action: @escaping () -> Void) -> some View {
+        SigxShakeDetector.enable()
+        return self.onReceive(NotificationCenter.default.publisher(for: .sigxDeviceDidShake)) { _ in
+            action()
+        }
+    }
+}

package/ios/Sources/SigxDevClient/SigxDevClient.swift

@@ -0,0 +1,106 @@
+import Foundation
+import Lynx
+import ObjectiveC.runtime
+
+/// Facade API for sigx-lynx iOS dev client.
+///
+/// Templates call these methods in order:
+/// 1. `SigxDevClient.registerServices()` — BEFORE LynxSetupService.initialize(), enables debug preset
+/// 2. `SigxDevClient.enableDevMode()` — AFTER LynxSetupService.initialize(), enables devtool/logbox
+/// 3. `SigxDevClient.configureForDev(builder:)` — in LynxView setup for dev mode
+class SigxDevClient {
+
+    /// Enable lynxDebug on LynxEnv so that prepareConfig can initialize devtool env.
+    /// Call BEFORE LynxSetupService.shared.initialize() in `#if DEBUG`.
+    static func registerServices() {
+        let env = LynxEnv.sharedInstance()
+        env.lynxDebugEnabled = true
+
+        // Mirror Android's setLogBoxPresetValue(true): LynxEnv.logBoxEnabled
+        // ANDs in `[LynxService(LynxServiceDevToolProtocol) logBoxPresetValue]`,
+        // which is initialised to NO. Without this flip, errors give a silent
+        // white screen on iOS instead of the native Lynx logbox overlay.
+        // We dispatch through the Obj-C runtime (rather than the typed Swift
+        // import) because the Lynx pods don't ship a Swift-friendly facade
+        // for `+[LynxServices getInstanceWithProtocol:]`.
+        setDevToolPresetValue(true, forKey: "logBoxPresetValue")
+
+        print("[SigxDevClient] Set lynxDebugEnabled and logBoxPresetValue (before prepareConfig)")
+    }
+
+    /// Flip a BOOL `@property` on the registered `LynxServiceDevToolProtocol`
+    /// service instance via Obj-C runtime + KVC.
+    private static func setDevToolPresetValue(_ value: Bool, forKey key: String) {
+        guard let servicesCls = NSClassFromString("LynxServices") else { return }
+        guard let proto = NSProtocolFromString("LynxServiceDevToolProtocol") else { return }
+        let sel = NSSelectorFromString("getInstanceWithProtocol:")
+        guard let method = class_getClassMethod(servicesCls, sel) else { return }
+
+        typealias GetInstanceFn = @convention(c) (AnyClass, Selector, Protocol) -> NSObject?
+        let fn = unsafeBitCast(method_getImplementation(method), to: GetInstanceFn.self)
+        if let svc = fn(servicesCls, sel, proto) {
+            svc.setValue(value, forKey: key)
+        }
+    }
+
+    /// Enable devtool and logbox flags on LynxEnv.
+    /// MUST be called AFTER LynxSetupService.shared.initialize() (i.e. after prepareConfig).
+    static func enableDevMode() {
+        let env = LynxEnv.sharedInstance()
+        env.devtoolEnabled = true
+        env.logBoxEnabled = true
+        print("[SigxDevClient] Enabled devtool and logbox on LynxEnv (after init)")
+    }
+
+    /// Configure a LynxView builder for dev mode (HTTP resource fetching + HMR).
+    /// Call when launching with a dev server URL.
+    static func configureForDev(builder: LynxViewBuilder) {
+        builder.templateResourceFetcher = DevTemplateResourceFetcher()
+        builder.enableGenericResourceFetcher = .true
+        builder.genericResourceFetcher = DevGenericResourceFetcher()
+        print("[SigxDevClient] Configured LynxViewBuilder for dev mode (resource fetchers)")
+    }
+
+    private static let lastConnectedUrlKey = "sigx_dev_client.last_connected_url"
+    private static let recentUrlsKey = "sigx_dev_client.recent_urls"
+    private static let recentUrlsMax = 20
+
+    /// Most recently used dev-server URL, persisted across launches so the app
+    /// can reconnect after a warm restart (icon-tap with no `--sigx_dev_url`
+    /// launch argument). Mirror of Android's `DevSettings.lastConnectedUrl`.
+    static var lastConnectedUrl: String? {
+        get {
+            let value = UserDefaults.standard.string(forKey: lastConnectedUrlKey)
+            return (value?.isEmpty ?? true) ? nil : value
+        }
+        set {
+            UserDefaults.standard.set(newValue, forKey: lastConnectedUrlKey)
+        }
+    }
+
+    /// History of dev-server URLs the user has connected to from
+    /// `DevHomeScreen`, most-recent first. Capped at 20 entries.
+    public static var recentUrls: [String] {
+        UserDefaults.standard.stringArray(forKey: recentUrlsKey) ?? []
+    }
+
+    /// Insert `url` at the front of the recent-URLs list, dedup, and trim to
+    /// the cap. Also updates `lastConnectedUrl` so warm restarts reconnect.
+    public static func addRecentUrl(_ url: String) {
+        let trimmed = url.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        var urls = recentUrls.filter { $0 != trimmed }
+        urls.insert(trimmed, at: 0)
+        UserDefaults.standard.set(Array(urls.prefix(recentUrlsMax)), forKey: recentUrlsKey)
+        lastConnectedUrl = trimmed
+    }
+
+    public static func removeRecentUrl(_ url: String) {
+        let urls = recentUrls.filter { $0 != url }
+        UserDefaults.standard.set(urls, forKey: recentUrlsKey)
+    }
+
+    public static func clearRecentUrls() {
+        UserDefaults.standard.removeObject(forKey: recentUrlsKey)
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@sigx/lynx-dev-client",
+  "version": "0.1.0",
+  "description": "Dev client for sigx-lynx — resource fetchers, template provider, and devtool integration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./sigx-module.json": "./sigx-module.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "android",
+    "ios"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  }
+}