nebula-tv: Skill for Claude Code

Nebula Coroutines Reference

Distilled from official Kotlin docs and battle-tested patterns. All examples are Nebula-context (widget refresh, browser, app grid).

1. stateIn(WhileSubscribed) — The Standard ViewModel Pattern

Always use this when exposing StateFlow from a ViewModel:

class NasaApodViewModel(private val repo: NasaApodRepository) : ViewModel() {

    val state: StateFlow<ApodState> = repo.apodFlow()  // cold Flow from repo/DataStore
        .map { data -> ApodState.Success(data, Instant.now()) }
        .catch { e -> emit(ApodState.Error(e.message ?: "Failed")) }
        .stateIn(
            scope = viewModelScope,
            started = SharingStarted.WhileSubscribed(stopTimeoutMillis = 5_000),  // 5s grace period
            initialValue = ApodState.Loading
        )
}

Why WhileSubscribed(5000)?

• Upstream Flow stops collecting 5 seconds after the last subscriber (UI) disappears
• 5-second grace period survives Android screen rotations without restarting the upstream
• Automatically resumes when a new subscriber arrives (launcher comes back to foreground)
• Saves CPU + battery when Nebula launcher is backgrounded
• ❌ SharingStarted.Eagerly — keeps collecting forever, even when backgrounded
• ❌ SharingStarted.Lazily — never stops collecting once started

2. CancellationException — NEVER Catch It Silently

This is the most dangerous coroutine mistake. CancellationException extends Exception, so catch (e: Exception) will eat it — breaking structured concurrency.

// ✅ CORRECT: explicitly rethrow CancellationException
try {
    val data = withTimeout(30.seconds) { api.fetchApod(key) }
    _state.value = ApodState.Success(data, Instant.now())
} catch (e: TimeoutCancellationException) {
    // withTimeout throws TimeoutCancellationException (a CancellationException subclass)
    // Safe to catch this specific subtype — it's OUR timeout, not parent cancellation
    _state.value = ApodState.Error("Request timed out after 30s")
} catch (e: CancellationException) {
    throw e  // ← MUST RETHROW. This coroutine's parent is cancelling — let it propagate.
} catch (e: IOException) {
    _state.value = ApodState.Error("Network error: ${e.message}")
} catch (e: Exception) {
    _state.value = ApodState.Error(e.message ?: "Unknown error")
}