@sigx/lynx-dev-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andreas Ekdahl
+
+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/android/src/main/kotlin/com/sigx/devclient/DevGenericResourceFetcher.kt

@@ -0,0 +1,73 @@
+package com.sigx.devclient
+
+import com.lynx.tasm.resourceprovider.LynxResourceCallback
+import com.lynx.tasm.resourceprovider.LynxResourceRequest
+import com.lynx.tasm.resourceprovider.LynxResourceResponse
+import com.lynx.tasm.resourceprovider.generic.LynxGenericResourceFetcher
+import com.lynx.tasm.resourceprovider.generic.StreamDelegate
+import okhttp3.Call
+import okhttp3.Callback
+import okhttp3.OkHttpClient
+import okhttp3.Request
+import okhttp3.Response
+import java.io.IOException
+import java.util.concurrent.TimeUnit
+
+/**
+ * Handles generic resource fetching (JS chunks, CSS, JSON, etc.) for LynxView.
+ * Required for HMR hot-update JSON/JS fetches.
+ */
+@Suppress("UNCHECKED_CAST")
+class DevGenericResourceFetcher : LynxGenericResourceFetcher() {
+
+    private val httpClient = OkHttpClient.Builder()
+        .connectTimeout(10, TimeUnit.SECONDS)
+        .readTimeout(30, TimeUnit.SECONDS)
+        .build()
+
+    override fun fetchResource(
+        request: LynxResourceRequest,
+        callback: LynxResourceCallback<ByteArray>
+    ) {
+        if (request == null) {
+            callback.onResponse(failed("request is null"))
+            return
+        }
+
+        val httpRequest = Request.Builder().url(request.url).build()
+        httpClient.newCall(httpRequest).enqueue(object : Callback {
+            override fun onResponse(call: Call, response: Response) {
+                response.use {
+                    if (it.isSuccessful && it.body != null) {
+                        callback.onResponse(LynxResourceResponse.onSuccess(it.body!!.bytes()))
+                    } else {
+                        callback.onResponse(failed("HTTP ${it.code}: ${it.message}"))
+                    }
+                }
+            }
+
+            override fun onFailure(call: Call, e: IOException) {
+                callback.onResponse(failed(e))
+            }
+        })
+    }
+
+    override fun fetchResourcePath(
+        request: LynxResourceRequest,
+        callback: LynxResourceCallback<String>
+    ) {
+        callback.onResponse(failed("fetchResourcePath not supported"))
+    }
+
+    override fun fetchStream(request: LynxResourceRequest, delegate: StreamDelegate) {
+        delegate.onError("fetchStream not supported")
+    }
+
+    override fun cancel(request: LynxResourceRequest) {}
+
+    private fun <T> failed(message: String): LynxResourceResponse<T> =
+        LynxResourceResponse.onFailed(Throwable(message)) as LynxResourceResponse<T>
+
+    private fun <T> failed(e: Throwable): LynxResourceResponse<T> =
+        LynxResourceResponse.onFailed(e) as LynxResourceResponse<T>
+}

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

@@ -0,0 +1,163 @@
+package com.sigx.devclient
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.*
+import androidx.compose.foundation.lazy.LazyColumn
+import androidx.compose.foundation.lazy.items
+import androidx.compose.foundation.text.KeyboardActions
+import androidx.compose.foundation.text.KeyboardOptions
+import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Delete
+import androidx.compose.material.icons.filled.QrCodeScanner
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.text.input.ImeAction
+import androidx.compose.ui.text.input.KeyboardType
+import androidx.compose.ui.unit.dp
+
+/**
+ * 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 `EXTRA_DEV_URL` intent extra AND no `main.lynx.bundle` asset.
+ *
+ * `onSelectUrl` fires when the user picks a URL — the parent (template's
+ * MainActivity) holds that in state and re-composes to render `DevLynxScreen`.
+ */
+@OptIn(ExperimentalMaterial3Api::class)
+@Composable
+fun DevHomeScreen(
+    onSelectUrl: (String) -> Unit,
+) {
+    val context = LocalContext.current
+    val devSettings = remember { DevSettings(context) }
+    var urlText by remember { mutableStateOf("") }
+    var recentUrls by remember { mutableStateOf(devSettings.recentUrls) }
+    var showQRScanner by remember { mutableStateOf(false) }
+
+    fun connectToUrl(url: String) {
+        val trimmed = url.trim()
+        if (trimmed.isBlank()) return
+        devSettings.addRecentUrl(trimmed)
+        recentUrls = devSettings.recentUrls
+        onSelectUrl(trimmed)
+    }
+
+    if (showQRScanner) {
+        DevQRScanner(
+            onCodeScanned = { code ->
+                showQRScanner = false
+                urlText = code
+                connectToUrl(code)
+            },
+            onBack = { showQRScanner = false },
+        )
+        return
+    }
+
+    Scaffold(
+        topBar = {
+            TopAppBar(
+                title = { Text("sigx-lynx dev") },
+                actions = {
+                    IconButton(onClick = { showQRScanner = true }) {
+                        Icon(Icons.Default.QrCodeScanner, contentDescription = "Scan QR")
+                    }
+                },
+            )
+        },
+    ) { padding ->
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .padding(padding)
+                .padding(16.dp),
+        ) {
+            OutlinedTextField(
+                value = urlText,
+                onValueChange = { urlText = it },
+                label = { Text("Dev server URL") },
+                placeholder = { Text("http://192.168.1.100:3000/main.lynx.bundle") },
+                modifier = Modifier.fillMaxWidth(),
+                singleLine = true,
+                keyboardOptions = KeyboardOptions(
+                    keyboardType = KeyboardType.Uri,
+                    imeAction = ImeAction.Go,
+                ),
+                keyboardActions = KeyboardActions(
+                    onGo = { connectToUrl(urlText) },
+                ),
+            )
+
+            Spacer(modifier = Modifier.height(12.dp))
+
+            Button(
+                onClick = { connectToUrl(urlText) },
+                modifier = Modifier.fillMaxWidth(),
+                enabled = urlText.isNotBlank(),
+            ) {
+                Text("Connect")
+            }
+
+            Spacer(modifier = Modifier.height(24.dp))
+
+            if (recentUrls.isNotEmpty()) {
+                Row(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.SpaceBetween,
+                    verticalAlignment = Alignment.CenterVertically,
+                ) {
+                    Text(
+                        "Recent",
+                        style = MaterialTheme.typography.titleMedium,
+                    )
+                    TextButton(onClick = {
+                        devSettings.clearRecentUrls()
+                        recentUrls = emptyList()
+                    }) {
+                        Text("Clear")
+                    }
+                }
+
+                Spacer(modifier = Modifier.height(8.dp))
+
+                LazyColumn {
+                    items(recentUrls) { url ->
+                        ListItem(
+                            headlineContent = { Text(url, maxLines = 1) },
+                            modifier = Modifier.clickable {
+                                urlText = url
+                                connectToUrl(url)
+                            },
+                            trailingContent = {
+                                IconButton(onClick = {
+                                    devSettings.removeRecentUrl(url)
+                                    recentUrls = devSettings.recentUrls
+                                }) {
+                                    Icon(Icons.Default.Delete, contentDescription = "Remove")
+                                }
+                            },
+                        )
+                        HorizontalDivider()
+                    }
+                }
+            } else {
+                Spacer(modifier = Modifier.weight(1f))
+                Column(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalAlignment = Alignment.CenterHorizontally,
+                ) {
+                    Text(
+                        "Enter a dev server URL or scan a QR code",
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+                Spacer(modifier = Modifier.weight(1f))
+            }
+        }
+    }
+}

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

@@ -0,0 +1,208 @@
+package com.sigx.devclient
+
+import android.view.ViewGroup
+import androidx.activity.compose.BackHandler
+import androidx.compose.foundation.layout.*
+import androidx.compose.material3.*
+import androidx.compose.runtime.*
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.platform.LocalContext
+import androidx.compose.ui.viewinterop.AndroidView
+import com.lynx.tasm.LynxView
+import com.lynx.tasm.LynxViewBuilder
+import com.lynx.tasm.TemplateData
+import com.lynx.xelement.XElementBehaviors
+
+/**
+ * Full-featured dev screen that wraps a LynxView with the complete sigx dev experience:
+ * - HMR via dev-client resource fetchers
+ * - Shake-to-open dev menu
+ * - Performance HUD overlay
+ * - Error overlay (red screen)
+ * - Dev settings persistence
+ *
+ * Use this as a drop-in replacement for manual LynxView setup in dev mode.
+ */
+@Composable
+fun DevLynxScreen(
+    url: String,
+    onBack: (() -> Unit)? = null,
+    /** Optional list of native module names to show in dev menu. */
+    nativeModules: List<String> = emptyList(),
+    /**
+     * Called once per LynxView after construction. Use to attach lifecycle
+     * publishers (e.g. `GeneratedLifecyclePublishers.attachAll(lynxView)`).
+     * Called BEFORE renderTemplateUrl so per-view initial state (safe-area
+     * insets, etc.) lands before the first MT paint.
+     */
+    onLynxViewCreated: ((LynxView) -> Unit)? = null,
+) {
+    var loading by remember { mutableStateOf(true) }
+    var error by remember { mutableStateOf<String?>(null) }
+    var showDevMenu by remember { mutableStateOf(false) }
+    var currentUrl by remember { mutableStateOf(url) }
+    val context = LocalContext.current
+    val devSettings = remember { DevSettings(context) }
+
+    var lynxViewRef by remember { mutableStateOf<LynxView?>(null) }
+    var perfHudEnabled by remember { mutableStateOf(devSettings.perfHudEnabled) }
+    var logBoxEnabled by remember { mutableStateOf(devSettings.logBoxEnabled) }
+    var inspectorEnabled by remember { mutableStateOf(false) }
+
+    // Persist last connected URL
+    LaunchedEffect(currentUrl) {
+        devSettings.lastConnectedUrl = currentUrl
+    }
+
+    // Shake detector
+    DisposableEffect(Unit) {
+        val shakeDetector = ShakeDetector(context) {
+            showDevMenu = true
+        }
+        shakeDetector.start()
+        onDispose { shakeDetector.stop() }
+    }
+
+    // Wire the system back gesture/button to onBack. Without this, system
+    // back falls through to the activity's default behavior (typically
+    // finish()), which kills the app instead of returning to a sandbox
+    // host's DevHomeScreen. When onBack is null (caller wants no back
+    // affordance) we leave the default behavior alone.
+    if (onBack != null) {
+        BackHandler { onBack() }
+    }
+
+    Box(modifier = Modifier.fillMaxSize()) {
+        AndroidView(
+            modifier = Modifier.fillMaxSize(),
+            factory = { ctx ->
+                try {
+                    val viewBuilder = LynxViewBuilder()
+                    viewBuilder.addBehaviors(XElementBehaviors().create())
+                    SigxDevClient.configureForDev(viewBuilder, ctx)
+
+                    val lynxView = viewBuilder.build(ctx)
+                    lynxView.layoutParams = ViewGroup.LayoutParams(
+                        ViewGroup.LayoutParams.MATCH_PARENT,
+                        ViewGroup.LayoutParams.MATCH_PARENT
+                    )
+
+                    // Lifecycle publishers (safe-area, future device
+                    // observers) attach BEFORE renderTemplate so each
+                    // publisher's initial updateGlobalProps lands before
+                    // the first MT paint.
+                    onLynxViewCreated?.invoke(lynxView)
+
+                    lynxView.renderTemplateUrl(currentUrl, TemplateData.empty())
+                    lynxViewRef = lynxView
+                    loading = false
+                    lynxView
+                } catch (e: Exception) {
+                    error = e.message ?: "Failed to create LynxView"
+                    loading = false
+                    android.view.View(ctx)
+                }
+            }
+        )
+
+        if (loading) {
+            CircularProgressIndicator(
+                modifier = Modifier.align(Alignment.Center)
+            )
+        }
+
+        // Performance HUD overlay
+        PerfHud(
+            visible = perfHudEnabled,
+            lynxView = lynxViewRef,
+            modifier = Modifier.align(Alignment.TopEnd)
+        )
+
+        // Error overlay
+        ErrorOverlay(
+            error = error,
+            onDismiss = { error = null },
+            onReload = {
+                error = null
+                lynxViewRef?.let { view ->
+                    loading = true
+                    try {
+                        view.reloadAndInit()
+                        view.renderTemplateUrl(currentUrl, TemplateData.empty())
+                    } catch (e: Exception) {
+                        error = e.message ?: "Reload failed"
+                    }
+                    loading = false
+                }
+            }
+        )
+    }
+
+    // Dev Menu
+    DevMenu(
+        visible = showDevMenu,
+        onDismiss = { showDevMenu = false },
+        actions = DevMenuActions(
+            onReload = {
+                lynxViewRef?.let { view ->
+                    loading = true
+                    error = null
+                    try {
+                        view.reloadAndInit()
+                        view.renderTemplateUrl(currentUrl, TemplateData.empty())
+                    } catch (e: Exception) {
+                        error = e.message ?: "Reload failed"
+                    }
+                    loading = false
+                }
+            },
+            onChangeUrl = { newUrl ->
+                currentUrl = newUrl
+                lynxViewRef?.let { view ->
+                    loading = true
+                    error = null
+                    try {
+                        view.renderTemplateUrl(newUrl, TemplateData.empty())
+                    } catch (e: Exception) {
+                        error = e.message ?: "Failed to load URL"
+                    }
+                    loading = false
+                }
+            },
+            onGoHome = onBack,
+            onTogglePerfHud = {
+                perfHudEnabled = !perfHudEnabled
+                devSettings.perfHudEnabled = perfHudEnabled
+            },
+            onToggleLogBox = {
+                logBoxEnabled = !logBoxEnabled
+                devSettings.logBoxEnabled = logBoxEnabled
+                try {
+                    val cls = Class.forName("com.lynx.service.devtool.LynxDevToolService")
+                    val instance = cls.getMethod("getINSTANCE").invoke(null)
+                    cls.getMethod("setLogBoxPresetValue", Boolean::class.java)
+                        .invoke(instance, logBoxEnabled)
+                } catch (_: Exception) {}
+            },
+            onToggleInspector = {
+                inspectorEnabled = !inspectorEnabled
+                if (inspectorEnabled) {
+                    lynxViewRef?.let { view ->
+                        try {
+                            val cls = Class.forName("com.lynx.service.devtool.LynxDevToolService")
+                            val instance = cls.getMethod("getINSTANCE").invoke(null)
+                            cls.getMethod("createInspectorOwner", com.lynx.tasm.LynxView::class.java, Boolean::class.java)
+                                .invoke(instance, view, true)
+                        } catch (_: Exception) {}
+                    }
+                }
+            },
+            currentUrl = currentUrl,
+            perfHudEnabled = perfHudEnabled,
+            logBoxEnabled = logBoxEnabled,
+            inspectorEnabled = inspectorEnabled,
+            nativeModules = nativeModules
+        )
+    )
+}