@sigx/lynx-dev-client 0.1.0

package/android/src/main/kotlin/com/sigx/devclient/ErrorOverlay.kt

@@ -0,0 +1,86 @@
+package com.sigx.devclient
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.material3.Button
+import androidx.compose.material3.ButtonDefaults
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+
+/**
+ * React Native-style red screen error overlay.
+ * Shows error message and stack trace with dismiss/reload actions.
+ */
+@Composable
+fun ErrorOverlay(
+    error: String?,
+    onDismiss: () -> Unit,
+    onReload: () -> Unit
+) {
+    if (error == null) return
+
+    Box(
+        modifier = Modifier
+            .fillMaxSize()
+            .background(Color(0xFFCC0000))
+    ) {
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(24.dp)
+                .verticalScroll(rememberScrollState())
+        ) {
+            Text(
+                "Error",
+                color = Color.White,
+                fontSize = 24.sp,
+                fontWeight = FontWeight.Bold
+            )
+            Spacer(modifier = Modifier.height(16.dp))
+            Text(
+                error,
+                color = Color(0xFFFFCCCC),
+                fontSize = 14.sp,
+                fontFamily = FontFamily.Monospace,
+                lineHeight = 20.sp
+            )
+            Spacer(modifier = Modifier.height(24.dp))
+            Row(
+                horizontalArrangement = Arrangement.spacedBy(12.dp)
+            ) {
+                Button(
+                    onClick = onReload,
+                    colors = ButtonDefaults.buttonColors(
+                        containerColor = Color.White,
+                        contentColor = Color(0xFFCC0000)
+                    )
+                ) {
+                    Text("Reload", fontWeight = FontWeight.Bold)
+                }
+                Button(
+                    onClick = onDismiss,
+                    colors = ButtonDefaults.buttonColors(
+                        containerColor = Color(0x33FFFFFF),
+                        contentColor = Color.White
+                    )
+                ) {
+                    Text("Dismiss")
+                }
+            }
+            Spacer(modifier = Modifier.height(24.dp))
+            Text(
+                "sigx dev client -- shake device or press Menu to open dev tools",
+                color = Color(0x99FFFFFF),
+                fontSize = 11.sp
+            )
+        }
+    }
+}

package/android/src/main/kotlin/com/sigx/devclient/PerfHud.kt

@@ -0,0 +1,100 @@
+package com.sigx.devclient
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Text
+import androidx.compose.runtime.*
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.font.FontFamily
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import com.lynx.tasm.LynxPerfMetric
+import com.lynx.tasm.LynxView
+import kotlinx.coroutines.delay
+
+/**
+ * Translucent performance overlay showing key Lynx rendering metrics.
+ * Uses LynxView.forceGetPerf() to read timing data.
+ */
+@Composable
+fun PerfHud(
+    visible: Boolean,
+    lynxView: LynxView?,
+    modifier: Modifier = Modifier
+) {
+    if (!visible || lynxView == null) return
+
+    var metrics by remember { mutableStateOf<LynxPerfMetric?>(null) }
+
+    LaunchedEffect(lynxView) {
+        while (true) {
+            try {
+                metrics = lynxView.forceGetPerf()
+            } catch (_: Exception) {}
+            delay(2000)
+        }
+    }
+
+    Box(
+        modifier = modifier
+            .padding(8.dp)
+            .background(Color(0xCC1E1E1E), RoundedCornerShape(8.dp))
+            .padding(10.dp)
+    ) {
+        Column {
+            Text(
+                "sigx perf",
+                color = Color(0xFF7C3AED),
+                fontSize = 11.sp,
+                fontFamily = FontFamily.Monospace
+            )
+            Spacer(modifier = Modifier.height(4.dp))
+
+            metrics?.let { m ->
+                PerfLine("TTI", m.tti)
+                PerfLine("Layout", m.layout)
+                PerfLine("JS Core", m.jsFinishLoadCore)
+                PerfLine("JS App", m.jsFinishLoadApp)
+                PerfLine("TASM Decode", m.tasmBinaryDecode)
+                PerfLine("Render Page", m.renderPage)
+                PerfLine("Diff Root", m.diffRootCreate)
+                if (m.isHasActualFMP) {
+                    PerfLine("FMP", m.actualFMPDuration)
+                }
+            } ?: Text(
+                "Waiting for metrics...",
+                color = Color(0xFF94A3B8),
+                fontSize = 10.sp,
+                fontFamily = FontFamily.Monospace
+            )
+        }
+    }
+}
+
+@Composable
+private fun PerfLine(label: String, value: Double) {
+    if (value <= 0) return
+    Row(
+        modifier = Modifier.fillMaxWidth(),
+        horizontalArrangement = Arrangement.SpaceBetween
+    ) {
+        Text(
+            label,
+            color = Color(0xFF94A3B8),
+            fontSize = 10.sp,
+            fontFamily = FontFamily.Monospace
+        )
+        Text(
+            "%.1fms".format(value),
+            color = when {
+                value < 100 -> Color(0xFF22C55E)
+                value < 300 -> Color(0xFFEAB308)
+                else -> Color(0xFFEF4444)
+            },
+            fontSize = 10.sp,
+            fontFamily = FontFamily.Monospace
+        )
+    }
+}

package/android/src/main/kotlin/com/sigx/devclient/ShakeDetector.kt

@@ -0,0 +1,97 @@
+package com.sigx.devclient
+
+import android.content.Context
+import android.hardware.Sensor
+import android.hardware.SensorEvent
+import android.hardware.SensorEventListener
+import android.hardware.SensorManager
+import kotlin.math.sqrt
+
+/**
+ * Detects device shakes using the accelerometer.
+ * Ported from React Native's ShakeDetector
+ * (ReactAndroid/.../common/ShakeDetector.java) — requires sustained
+ * high-magnitude motion within a short window, not a single spike,
+ * so casual handling does not trigger it.
+ */
+class ShakeDetector(
+    private val context: Context,
+    private val onShake: () -> Unit
+) : SensorEventListener {
+
+    private var sensorManager: SensorManager? = null
+
+    private val timestamps = LongArray(MAX_SAMPLES)
+    private val magnitudes = FloatArray(MAX_SAMPLES)
+    private var currentIndex = 0
+    private var numShakes = 0
+    private var lastTimestamp = 0L
+
+    companion object {
+        private const val MAX_SAMPLES = 25
+        private const val MIN_TIME_BETWEEN_SAMPLES_NS = 20_000_000L   // 20 ms
+        private const val VISIBLE_TIME_RANGE_NS = 500_000_000L        // 500 ms
+        private const val ACCELERATION_THRESHOLD = 15f                // m/s² (~1.5× gravity)
+        private const val MIN_NUM_SHAKES = 1
+    }
+
+    fun start() {
+        sensorManager = context.getSystemService(Context.SENSOR_SERVICE) as? SensorManager
+        sensorManager?.getDefaultSensor(Sensor.TYPE_ACCELEROMETER)?.let { sensor ->
+            sensorManager?.registerListener(this, sensor, SensorManager.SENSOR_DELAY_GAME)
+        }
+        reset()
+    }
+
+    fun stop() {
+        sensorManager?.unregisterListener(this)
+        sensorManager = null
+        reset()
+    }
+
+    override fun onSensorChanged(event: SensorEvent?) {
+        val e = event ?: return
+        if (e.timestamp - lastTimestamp < MIN_TIME_BETWEEN_SAMPLES_NS) return
+        lastTimestamp = e.timestamp
+
+        val ax = e.values[0]
+        val ay = e.values[1]
+        val az = e.values[2]
+
+        timestamps[currentIndex] = e.timestamp
+        magnitudes[currentIndex] = sqrt(ax * ax + ay * ay + az * az)
+
+        maybeDispatchShake(e.timestamp)
+        currentIndex = (currentIndex + 1) % MAX_SAMPLES
+    }
+
+    private fun maybeDispatchShake(now: Long) {
+        if (numShakes >= 8 * MIN_NUM_SHAKES) {
+            reset()
+            onShake()
+            return
+        }
+
+        var count = 0
+        for (i in 0 until MAX_SAMPLES) {
+            val idx = (currentIndex - i + MAX_SAMPLES) % MAX_SAMPLES
+            if (now - timestamps[idx] > VISIBLE_TIME_RANGE_NS) break
+            if (magnitudes[idx] > ACCELERATION_THRESHOLD) {
+                count++
+            }
+        }
+        numShakes = count
+    }
+
+    private fun reset() {
+        numShakes = 0
+        lastTimestamp = 0L
+        currentIndex = 0
+        for (i in 0 until MAX_SAMPLES) {
+            timestamps[i] = 0L
+            magnitudes[i] = 0f
+        }
+    }
+
+    override fun onAccuracyChanged(sensor: Sensor?, accuracy: Int) {}
+}

package/android/src/main/kotlin/com/sigx/devclient/SigxDevClient.kt

@@ -0,0 +1,91 @@
+package com.sigx.devclient
+
+import android.app.Application
+import android.content.Context
+import android.util.Log
+import com.lynx.tasm.LynxBooleanOption
+import com.lynx.tasm.LynxEnv
+import com.lynx.tasm.LynxViewBuilder
+import com.lynx.tasm.service.LynxServiceCenter
+
+/**
+ * Facade API for sigx-lynx dev client.
+ *
+ * Templates call these methods in order:
+ * 1. `SigxDevClient.registerServices()` -- before LynxEnv.init(), registers devtool service
+ * 2. `SigxDevClient.enableDevMode()` -- after LynxEnv.init(), enables debug/devtool/logbox
+ * 3. `SigxDevClient.configureForDev(builder, context)` -- in LynxView setup for dev mode
+ */
+object SigxDevClient {
+
+    private const val TAG = "SigxDevClient"
+
+    /**
+     * Register LynxDevToolService with the service center.
+     * Call BEFORE LynxEnv.inst().init() inside a BuildConfig.DEBUG check.
+     */
+    fun registerServices() {
+        try {
+            val devToolServiceClass = Class.forName("com.lynx.service.devtool.LynxDevToolService")
+
+            // LynxDevToolService.INSTANCE is a Kotlin lazy companion property,
+            // accessed via the static getINSTANCE() method (not a field).
+            val getInstanceMethod = devToolServiceClass.getMethod("getINSTANCE")
+            val instance = getInstanceMethod.invoke(null)
+                ?: throw IllegalStateException("LynxDevToolService.getINSTANCE() returned null")
+
+            // Register with LynxServiceCenter
+            val center = LynxServiceCenter.inst()
+            val registerMethod = center.javaClass.methods.firstOrNull {
+                it.name == "registerService" &&
+                it.parameterTypes.size == 1 &&
+                it.parameterTypes[0].isAssignableFrom(instance.javaClass)
+            } ?: center.javaClass.methods.first { it.name == "registerService" }
+
+            registerMethod.invoke(center, instance)
+            Log.i(TAG, "Registered LynxDevToolService")
+
+            // Set preset values via the concrete class methods
+            devToolServiceClass.getMethod("setLynxDebugPresetValue", Boolean::class.java)
+                .invoke(instance, true)
+            devToolServiceClass.getMethod("setLogBoxPresetValue", Boolean::class.java)
+                .invoke(instance, true)
+            Log.i(TAG, "Set debug preset values")
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to register devtool service: ${e.message}", e)
+        }
+    }
+
+    /**
+     * Enable debug features on LynxEnv.
+     * MUST be called AFTER LynxEnv.inst().init() -- calling before init() has
+     * no effect because init() resets these flags.
+     */
+    fun enableDevMode() {
+        LynxEnv.inst().enableLynxDebug(true)
+        LynxEnv.inst().enableDevtool(true)
+        LynxEnv.inst().enableLogBox(true)
+        Log.i(TAG, "Enabled devtool, debug, and logbox on LynxEnv (after init)")
+    }
+
+    /**
+     * Convenience method that calls registerServices() + enableDevMode().
+     * Only use this if you've already called LynxEnv.inst().init().
+     */
+    fun init(app: Application) {
+        registerServices()
+        enableDevMode()
+    }
+
+    /**
+     * Configure a LynxViewBuilder for dev mode (HTTP resource fetching + HMR).
+     * Call when launching with a dev server URL.
+     */
+    fun configureForDev(builder: LynxViewBuilder, context: Context) {
+        builder.setTemplateProvider(DevTemplateProvider(context))
+        builder.setTemplateResourceFetcher(DevTemplateResourceFetcher(context))
+        builder.setEnableGenericResourceFetcher(LynxBooleanOption.TRUE)
+        builder.setGenericResourceFetcher(DevGenericResourceFetcher())
+        Log.i(TAG, "Configured LynxViewBuilder for dev mode (template provider + resource fetchers)")
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @sigx/lynx-dev-client
+ *
+ * Dev client for sigx-lynx apps. Contains native resource fetchers,
+ * template provider, and devtool integration that enable HMR and
+ * dev tools in debug builds.
+ *
+ * The JS side is a no-op — all functionality is in the native code
+ * that gets auto-linked during prebuild.
+ */
+export declare const DEV_CLIENT_VERSION = "0.1.0";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @sigx/lynx-dev-client
+ *
+ * Dev client for sigx-lynx apps. Contains native resource fetchers,
+ * template provider, and devtool integration that enable HMR and
+ * dev tools in debug builds.
+ *
+ * The JS side is a no-op — all functionality is in the native code
+ * that gets auto-linked during prebuild.
+ */
+export const DEV_CLIENT_VERSION = '0.1.0';

package/ios/Sources/SigxDevClient/DevGenericResourceFetcher.swift

@@ -0,0 +1,47 @@
+import Foundation
+import Lynx
+
+/// Handles generic resource fetching (JS chunks, CSS, JSON) for LynxView.
+/// Required for HMR hot-update JSON/JS fetches during development.
+class DevGenericResourceFetcher: NSObject, LynxGenericResourceFetcher {
+
+    private let session: URLSession = {
+        let config = URLSessionConfiguration.default
+        config.timeoutIntervalForRequest = 30
+        config.timeoutIntervalForResource = 60
+        return URLSession(configuration: config)
+    }()
+
+    func fetchResource(
+        _ request: LynxResourceRequest,
+        onComplete callback: @escaping LynxGenericResourceCompletionBlock
+    ) -> (() -> Void)! {
+        guard let url = URL(string: request.url ?? "") else {
+            callback(nil, NSError(domain: "com.sigx.devclient", code: 400,
+                                  userInfo: [NSLocalizedDescriptionKey: "Invalid URL: \(request.url ?? "")"]))
+            return {}
+        }
+
+        let task = session.dataTask(with: url) { data, response, error in
+            if let error = error {
+                callback(nil, error)
+                return
+            }
+            callback(data, nil)
+        }
+        task.resume()
+
+        // Return cancellation block
+        return { task.cancel() }
+    }
+
+    func fetchResourcePath(
+        _ request: LynxResourceRequest,
+        onComplete callback: @escaping LynxGenericResourcePathCompletionBlock
+    ) -> (() -> Void)! {
+        // Not used for dev server fetching — return error
+        callback(nil, NSError(domain: "com.sigx.devclient", code: 501,
+                              userInfo: [NSLocalizedDescriptionKey: "fetchResourcePath not implemented"]))
+        return {}
+    }
+}

package/ios/Sources/SigxDevClient/DevHomeScreen.swift

@@ -0,0 +1,128 @@
+import SwiftUI
+
+/// Dev-mode landing screen for sigx-lynx apps that ship without a bundled
+/// `main.lynx.bundle`. Lets the user enter a dev-server URL by hand, scan a
+/// QR code, or pick from recent URLs. The app template renders this when it
+/// has no `--sigx_dev_url` launch arg AND no bundle in `Bundle.main`.
+///
+/// Wraps itself in a `NavigationStack` so it owns the title bar; consumer just
+/// drops `DevHomeScreen { url in /* navigate to LynxView */ }` at the root.
+public struct DevHomeScreen: View {
+    let onSelectUrl: (String) -> Void
+
+    @State private var urlText = ""
+    @State private var recentUrls: [String] = []
+    @State private var showQRScanner = false
+
+    public init(onSelectUrl: @escaping (String) -> Void) {
+        self.onSelectUrl = onSelectUrl
+    }
+
+    public var body: some View {
+        // NavigationView (iOS 13+) rather than NavigationStack (iOS 16+) so
+        // the dev client works on apps with deployment target 15.0.
+        NavigationView {
+            VStack(spacing: 0) {
+                VStack(spacing: 12) {
+                    HStack {
+                        TextField("Dev server URL", text: $urlText)
+                            .textFieldStyle(.roundedBorder)
+                            .keyboardType(.URL)
+                            .autocapitalization(.none)
+                            .disableAutocorrection(true)
+                            .submitLabel(.go)
+                            .onSubmit { connect() }
+
+                        Button(action: { showQRScanner = true }) {
+                            Image(systemName: "qrcode.viewfinder")
+                                .font(.title2)
+                        }
+                    }
+
+                    Button(action: connect) {
+                        Text("Connect")
+                            .frame(maxWidth: .infinity)
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(urlText.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+                }
+                .padding()
+
+                Divider()
+
+                if recentUrls.isEmpty {
+                    Spacer()
+                    VStack(spacing: 8) {
+                        Image(systemName: "antenna.radiowaves.left.and.right")
+                            .font(.largeTitle)
+                            .foregroundColor(.secondary)
+                        Text("Enter a dev server URL or scan a QR code")
+                            .foregroundColor(.secondary)
+                            .multilineTextAlignment(.center)
+                    }
+                    .padding()
+                    Spacer()
+                } else {
+                    HStack {
+                        Text("Recent")
+                            .font(.headline)
+                        Spacer()
+                        Button("Clear") {
+                            SigxDevClient.clearRecentUrls()
+                            recentUrls = []
+                        }
+                        .font(.subheadline)
+                    }
+                    .padding(.horizontal)
+                    .padding(.top, 12)
+
+                    List {
+                        ForEach(recentUrls, id: \.self) { url in
+                            Button(action: {
+                                urlText = url
+                                connectTo(url)
+                            }) {
+                                Text(url)
+                                    .lineLimit(1)
+                                    .foregroundColor(.primary)
+                            }
+                        }
+                        .onDelete { indexSet in
+                            for index in indexSet {
+                                SigxDevClient.removeRecentUrl(recentUrls[index])
+                            }
+                            recentUrls = SigxDevClient.recentUrls
+                        }
+                    }
+                    .listStyle(.plain)
+                }
+            }
+            .navigationTitle("sigx-lynx dev")
+            .navigationBarTitleDisplayMode(.inline)
+            .sheet(isPresented: $showQRScanner) {
+                NavigationView {
+                    DevQRScanner { code in
+                        showQRScanner = false
+                        urlText = code
+                        connectTo(code)
+                    }
+                }
+            }
+            .onAppear {
+                recentUrls = SigxDevClient.recentUrls
+            }
+        }
+    }
+
+    private func connect() {
+        let trimmed = urlText.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        connectTo(trimmed)
+    }
+
+    private func connectTo(_ url: String) {
+        SigxDevClient.addRecentUrl(url)
+        recentUrls = SigxDevClient.recentUrls
+        onSelectUrl(url)
+    }
+}