Faster startup, resilient search, and real subway bullets

- Parse the 496-station catalog once off the main thread (StationCatalog) so the first frame renders immediately instead of a long black splash.
- Lazy HttpClient; all heavy work on Dispatchers.Default.
- CrashReporter: capture uncaught exceptions to a file and surface the trace on the home screen (no logcat needed on-device).
- RouteBadge: authentic monochrome subway bullets — filled circle (local) / diamond (express), route glyph reversed out. Used on home boards, search results, and station header.

Author: gi-os

examples/LightNYCSubway/src/main/kotlin/com/thelightphone/subway/ArrivalsRepository.kt

@@ -10,12 +10,14 @@ import kotlinx.coroutines.awaitAll
 import kotlinx.coroutines.coroutineScope
 
 /**
- * Fetches and decodes MTA realtime feeds, returning the upcoming arrivals for a
- * single station. Holds one [HttpClient]; remember to [close].
+ * Fetches and decodes MTA realtime feeds for a single station. The [HttpClient]
+ * is created lazily on first use (off the main thread) so it never slows startup.
  */
 class ArrivalsRepository {
 
-    private val client = HttpClient(OkHttp)
+    private var client: HttpClient? = null
+
+    private fun client(): HttpClient = client ?: HttpClient(OkHttp).also { client = it }
 
     /**
      * Query every feed that serves [station], decode it, and keep only the trains
@@ -42,11 +44,14 @@ class ArrivalsRepository {
 
     private suspend fun fetch(slug: String): List<GtfsRealtime.Raw> {
         // Pass the already-encoded URL string so the %2F survives to the server.
-        val bytes: ByteArray = client.get(MtaFeeds.url(slug)) {
+        val bytes: ByteArray = client().get(MtaFeeds.url(slug)) {
             header("Accept", "application/x-protobuf")
         }.body()
         return GtfsRealtime.parse(bytes)
     }
 
-    fun close() = client.close()
+    fun close() {
+        client?.close()
+        client = null
+    }
 }

examples/LightNYCSubway/src/main/kotlin/com/thelightphone/subway/CrashReporter.kt

@@ -0,0 +1,37 @@
+package com.thelightphone.subway
+
+import android.util.Log
+import java.io.File
+
+/**
+ * Captures uncaught exceptions to a file so the last crash can be shown on the
+ * home screen (the Light Phone has no easy logcat access). Also keeps the app
+ * from silently dying without a trace.
+ */
+object CrashReporter {
+    private const val FILE = "last_crash.txt"
+    private var dir: File? = null
+    private var installed = false
+
+    fun install(filesDir: File) {
+        if (installed) return
+        installed = true
+        dir = filesDir
+        val previous = Thread.getDefaultUncaughtExceptionHandler()
+        Thread.setDefaultUncaughtExceptionHandler { thread, error ->
+            runCatching {
+                File(filesDir, FILE).writeText(
+                    "Subway Times crash\n\n" + Log.getStackTraceString(error)
+                )
+            }
+            previous?.uncaughtException(thread, error)
+        }
+    }
+
+    fun lastCrash(): String? =
+        dir?.let { d -> File(d, FILE).takeIf { it.exists() }?.readText()?.takeIf { it.isNotBlank() } }
+
+    fun clear() {
+        dir?.let { runCatching { File(it, FILE).delete() } }
+    }
+}

examples/LightNYCSubway/src/main/kotlin/com/thelightphone/subway/HomeScreen.kt

@@ -8,7 +8,12 @@ import androidx.compose.foundation.layout.padding
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Modifier
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
 import androidx.lifecycle.viewModelScope
 import com.thelightphone.sdk.InitialScreen
 import com.thelightphone.sdk.LightScreen
@@ -46,7 +51,8 @@ data class HomeUiState(
 )
 
 class HomeViewModel(
-    private val store: StationStore,
+    private val dataStore: DataStore<Preferences>,
+    private val readAsset: (String) -> ByteArray,
 ) : LightViewModel<Unit>() {
 
     private val repo = ArrivalsRepository()
@@ -59,20 +65,23 @@ class HomeViewModel(
     }
 
     fun refresh() {
-        viewModelScope.launch(Dispatchers.IO) {
-            val starred = store.starredStations()
+        // All heavy work (catalog parse, network) happens off the main thread so
+        // the first frame renders immediately.
+        viewModelScope.launch(Dispatchers.Default) {
+            val stations = StationCatalog.load(readAsset)
+            val store = StationStore(dataStore, stations)
+            val starred = runCatching { store.starredStations() }.getOrDefault(emptyList())
             if (starred.isEmpty()) {
                 _state.value = HomeUiState(loading = false, boards = emptyList())
                 return@launch
             }
             _state.value = _state.value.copy(loading = true)
             val now = System.currentTimeMillis() / 1000
             val boards = starred.map { station ->
-                runCatching { repo.arrivalsFor(station, now) }
-                    .fold(
-                        onSuccess = { StationBoard(station, it.take(5)) },
-                        onFailure = { StationBoard(station, failed = true) },
-                    )
+                runCatching { repo.arrivalsFor(station, now) }.fold(
+                    onSuccess = { StationBoard(station, it.take(5)) },
+                    onFailure = { StationBoard(station, failed = true) },
+                )
             }
             _state.value = HomeUiState(loading = false, boards = boards, nowSeconds = now)
         }
@@ -91,23 +100,33 @@ class HomeScreen(sealedActivity: SealedLightActivity) :
     override val viewModelClass: Class<HomeViewModel> get() = HomeViewModel::class.java
 
     override fun createViewModel(): HomeViewModel {
-        val catalog = String(lightContext.readAsset("stations.json"), Charsets.UTF_8)
-        return HomeViewModel(StationStore(lightContext.dataStore, catalog))
+        CrashReporter.install(lightContext.filesDir)
+        return HomeViewModel(lightContext.dataStore, lightContext::readAsset)
     }
 
     @Composable
     override fun Content() {
         val state by viewModel.state.collectAsState()
         val themeColors by LightThemeController.colors.collectAsState()
+        val lastCrash = remember { CrashReporter.lastCrash() }
+        var showCrash by remember { mutableStateOf(lastCrash != null) }
 
         LightTheme(colors = themeColors) {
+            if (showCrash && lastCrash != null) {
+                CrashReportView(lastCrash) {
+                    CrashReporter.clear()
+                    showCrash = false
+                }
+                return@LightTheme
+            }
+
             Column(
                 modifier = Modifier
                     .fillMaxSize()
                     .background(LightThemeTokens.colors.background),
             ) {
                 LightTopBar(
-                    center = LightTopBarCenter.Text("Subway"),
+                    center = LightTopBarCenter.Text("Subway Times"),
                     rightButton = LightBarButton.LightIcon(
                         icon = LightIcons.SEARCH,
                         onClick = { navigateTo(::SearchScreen) },
@@ -172,11 +191,9 @@ private fun StationBoardView(
             .padding(bottom = 1f.gridUnitsAsDp()),
     ) {
         LightText(text = board.station.name, variant = LightTextVariant.Heading)
-        LightText(
-            text = board.station.routes.joinToString(" "),
-            variant = LightTextVariant.Detail,
-            lighten = true,
-            modifier = Modifier.padding(bottom = 0.25f.gridUnitsAsDp()),
+        RouteBadgeRow(
+            routes = board.station.routes,
+            modifier = Modifier.padding(top = 0.25f.gridUnitsAsDp(), bottom = 0.5f.gridUnitsAsDp()),
         )
         when {
             board.failed ->
@@ -187,3 +204,31 @@ private fun StationBoardView(
         }
     }
 }
+
+/** Shows the last captured crash so it can be read/screenshotted off-device. */
+@Composable
+private fun CrashReportView(trace: String, onDismiss: () -> Unit) {
+    Column(
+        modifier = Modifier
+            .fillMaxSize()
+            .background(LightThemeTokens.colors.background),
+    ) {
+        LightTopBar(
+            center = LightTopBarCenter.Text("Last error"),
+            modifier = Modifier.padding(bottom = 0.25f.gridUnitsAsDp()),
+        )
+        LightScrollView(
+            modifier = Modifier
+                .weight(1f)
+                .fillMaxWidth()
+                .padding(horizontal = 1f.gridUnitsAsDp()),
+        ) {
+            LightText(text = trace, variant = LightTextVariant.Detail)
+        }
+        LightBottomBar(
+            items = listOf(
+                LightBarButton.Text(text = "Dismiss", onClick = onDismiss),
+            ),
+        )
+    }
+}

examples/LightNYCSubway/src/main/kotlin/com/thelightphone/subway/SearchScreen.kt

@@ -9,6 +9,9 @@ import androidx.compose.runtime.Composable
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
 import androidx.compose.ui.Modifier
+import androidx.datastore.core.DataStore
+import androidx.datastore.preferences.core.Preferences
+import androidx.lifecycle.viewModelScope
 import com.thelightphone.sdk.LightScreen
 import com.thelightphone.sdk.LightViewModel
 import com.thelightphone.sdk.SealedLightActivity
@@ -25,18 +28,45 @@ import com.thelightphone.sdk.ui.LightTopBar
 import com.thelightphone.sdk.ui.LightTopBarCenter
 import com.thelightphone.sdk.ui.gridUnitsAsDp
 import com.thelightphone.sdk.ui.lightClickable
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.launch
+
+class SearchViewModel(
+    private val dataStore: DataStore<Preferences>,
+    private val readAsset: (String) -> ByteArray,
+) : LightViewModel<Unit>() {
+
+    @Volatile
+    private var store: StationStore? = null
 
-class SearchViewModel(val store: StationStore) : LightViewModel<Unit>() {
     private val _query = MutableStateFlow("")
     val query: StateFlow<String> = _query
     private val _results = MutableStateFlow<List<Station>>(emptyList())
     val results: StateFlow<List<Station>> = _results
 
+    init {
+        // Warm the catalog off the main thread so the first keystroke is instant.
+        viewModelScope.launch(Dispatchers.Default) {
+            store = StationStore(dataStore, StationCatalog.load(readAsset))
+            if (_query.value.isNotBlank()) {
+                _results.value = store?.search(_query.value).orEmpty()
+            }
+        }
+    }
+
     fun setQuery(q: String) {
         _query.value = q
-        _results.value = store.search(q)
+        val ready = store
+        if (ready != null) {
+            _results.value = ready.search(q)
+        } else {
+            viewModelScope.launch(Dispatchers.Default) {
+                val s = StationStore(dataStore, StationCatalog.load(readAsset)).also { store = it }
+                _results.value = s.search(q)
+            }
+        }
     }
 }
 
@@ -45,10 +75,8 @@ class SearchScreen(sealedActivity: SealedLightActivity) :
 
     override val viewModelClass: Class<SearchViewModel> get() = SearchViewModel::class.java
 
-    override fun createViewModel(): SearchViewModel {
-        val catalog = String(lightContext.readAsset("stations.json"), Charsets.UTF_8)
-        return SearchViewModel(StationStore(lightContext.dataStore, catalog))
-    }
+    override fun createViewModel(): SearchViewModel =
+        SearchViewModel(lightContext.dataStore, lightContext::readAsset)
 
     private fun openKeyboard() {
         navigateTo<String?>(
@@ -115,9 +143,12 @@ class SearchScreen(sealedActivity: SealedLightActivity) :
                                     .padding(bottom = 0.75f.gridUnitsAsDp()),
                             ) {
                                 LightText(text = station.name, variant = LightTextVariant.Copy)
+                                RouteBadgeRow(
+                                    routes = station.routes,
+                                    modifier = Modifier.padding(top = 0.25f.gridUnitsAsDp()),
+                                )
                                 LightText(
-                                    text = station.routes.joinToString(" ") +
-                                        "   ·   " + station.boroLabel,
+                                    text = station.boroLabel,
                                     variant = LightTextVariant.Detail,
                                     lighten = true,
                                 )

examples/LightNYCSubway/src/main/kotlin/com/thelightphone/subway/StationCatalog.kt

@@ -0,0 +1,37 @@
+package com.thelightphone.subway
+
+import kotlinx.serialization.json.Json
+
+/**
+ * Parses assets/stations.json exactly once and caches it process-wide.
+ *
+ * Parsing ~500 stations is CPU work that must NOT run on the main thread during
+ * composition (that was the long black screen at launch). Call [load] from a
+ * background dispatcher; every screen then shares the cached list instantly.
+ */
+object StationCatalog {
+
+    @Volatile
+    private var cache: List<Station>? = null
+
+    private val json = Json { ignoreUnknownKeys = true }
+
+    fun isLoaded(): Boolean = cache != null
+
+    fun cachedOrEmpty(): List<Station> = cache ?: emptyList()
+
+    /** Idempotent, thread-safe. Returns the parsed catalog (empty on failure). */
+    fun load(readAsset: (String) -> ByteArray): List<Station> {
+        cache?.let { return it }
+        return synchronized(this) {
+            cache ?: run {
+                val parsed = runCatching {
+                    val text = String(readAsset("stations.json"), Charsets.UTF_8)
+                    json.decodeFromString<StationsFile>(text).stations
+                }.getOrElse { emptyList() }
+                cache = parsed
+                parsed
+            }
+        }
+    }
+}