diff --git a/app/android/app/build.gradle.kts b/app/android/app/build.gradle.kts
index 5a16f7f3..054302b1 100644
--- a/app/android/app/build.gradle.kts
+++ b/app/android/app/build.gradle.kts
@@ -55,6 +55,8 @@ dependencies {
coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:2.1.4")
// The background notification socket (notify/NotificationService).
implementation("com.squareup.okhttp3:okhttp:4.12.0")
+ // NotificationCompat.MessagingStyle for the per-chat/run conversations (notify/NotificationPresenter).
+ implementation("androidx.core:core:1.15.0")
// JVM tests for the notification protocol and ledger (`gradlew :app:testDebugUnitTest`).
testImplementation("junit:junit:4.13.2")
// Android's org.json is a stub on the JVM; tests use the real implementation.
diff --git a/app/android/app/src/main/AndroidManifest.xml b/app/android/app/src/main/AndroidManifest.xml
index 8609352a..2e2bdf08 100644
--- a/app/android/app/src/main/AndroidManifest.xml
+++ b/app/android/app/src/main/AndroidManifest.xml
@@ -12,6 +12,11 @@
+
+
+
@@ -69,6 +74,11 @@
android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
android:value="Persistent connection to the user's self-hosted Pipelines server for instant notifications"/>
+
+
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ConnectWakeLock.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ConnectWakeLock.kt
new file mode 100644
index 00000000..7d68e2df
--- /dev/null
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ConnectWakeLock.kt
@@ -0,0 +1,27 @@
+package net.awan.pipelines_app.notify
+
+import android.content.Context
+import android.os.PowerManager
+
+/**
+ * A short partial wake lock held while the service opens its socket, so the
+ * CPU stays awake through the handshake. The timeout bounds it if no answer
+ * comes; [release] runs as soon as the socket opens or fails.
+ */
+class ConnectWakeLock(context: Context) {
+ private val lock = context.getSystemService(PowerManager::class.java)
+ .newWakeLock(PowerManager.PARTIAL_WAKE_LOCK, "pipelines:connect")
+ .apply { setReferenceCounted(false) }
+
+ fun hold() {
+ lock.acquire(HOLD_MILLIS)
+ }
+
+ fun release() {
+ if (lock.isHeld) lock.release()
+ }
+
+ companion object {
+ const val HOLD_MILLIS = 30_000L
+ }
+}
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ConnectionLog.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ConnectionLog.kt
new file mode 100644
index 00000000..2d9b85d9
--- /dev/null
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ConnectionLog.kt
@@ -0,0 +1,73 @@
+package net.awan.pipelines_app.notify
+
+import org.json.JSONArray
+import org.json.JSONException
+import org.json.JSONObject
+
+/** One entry of the connection log: when, what happened, and the error or HTTP code. */
+data class ConnectionEvent(
+ val timeMillis: Long,
+ val event: String,
+ val error: String?,
+ val code: Int?,
+)
+
+/**
+ * The last [CAPACITY] connection events, kept in the service's preferences so
+ * Settings can show why delivery stalled. Newest first. Error text is trimmed;
+ * the session cookie never reaches the log.
+ */
+class ConnectionLog(
+ private val store: LedgerStore,
+ private val clock: () -> Long = System::currentTimeMillis,
+) {
+ /** Read-modify-write: the main thread (task removal) and the service thread both log. */
+ @Synchronized
+ fun record(event: String, error: String? = null, code: Int? = null) {
+ val entry = ConnectionEvent(clock(), event, error?.take(MAX_ERROR_LENGTH), code)
+ store.putString(KEY, encode((listOf(entry) + entries()).take(CAPACITY)))
+ }
+
+ fun entries(): List = decode(store.getString(KEY))
+
+ companion object {
+ const val CAPACITY = 50
+ const val KEY = "connection.log"
+ private const val MAX_ERROR_LENGTH = 200
+
+ private fun encode(events: List): String {
+ val array = JSONArray()
+ for (event in events) {
+ array.put(
+ JSONObject()
+ .put("t", event.timeMillis)
+ .put("e", event.event)
+ .apply {
+ event.error?.let { put("x", it) }
+ event.code?.let { put("c", it) }
+ },
+ )
+ }
+ return array.toString()
+ }
+
+ /** A corrupt log reads as empty rather than breaking Settings. */
+ private fun decode(raw: String?): List {
+ if (raw.isNullOrEmpty()) return emptyList()
+ return try {
+ val array = JSONArray(raw)
+ (0 until array.length()).map { index ->
+ val item = array.getJSONObject(index)
+ ConnectionEvent(
+ timeMillis = item.getLong("t"),
+ event = item.getString("e"),
+ error = if (item.has("x")) item.getString("x") else null,
+ code = if (item.has("c")) item.getInt("c") else null,
+ )
+ }
+ } catch (_: JSONException) {
+ emptyList()
+ }
+ }
+ }
+}
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationDismissReceiver.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationDismissReceiver.kt
index 1d223c4d..f5bd713c 100644
--- a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationDismissReceiver.kt
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationDismissReceiver.kt
@@ -11,16 +11,20 @@ import android.content.Intent
class NotificationDismissReceiver : BroadcastReceiver() {
override fun onReceive(context: Context, intent: Intent) {
if (intent.action != ACTION) return
- val id = intent.getStringExtra(NotificationPresenter.EXTRA_NOTIFICATION_ID) ?: return
- queueClear(context, id)
+ val ids = intent.getStringExtra(NotificationPresenter.EXTRA_NOTIFICATION_ID) ?: return
+ queueClear(context, ids)
}
companion object {
const val ACTION = "net.awan.pipelines.notify.DISMISSED"
- /** Shared by dismissals and taps (see MainActivity). */
- fun queueClear(context: Context, id: String) {
- DeliveryLedger(ServiceSettings(context)).queueClear(listOf(id))
+ /**
+ * Shared by dismissals and taps (see MainActivity). [ids] is one server
+ * id or several separated by newlines, as a thread notification carries.
+ */
+ fun queueClear(context: Context, ids: String) {
+ DeliveryLedger(ServiceSettings(context))
+ .queueClear(ids.split('\n').filter { it.isNotEmpty() })
// Only nudge a running service; a stopped one sends the queue on
// its next connection.
if (NotificationService.running != null) {
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationPresenter.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationPresenter.kt
index 4db340a1..35a234a8 100644
--- a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationPresenter.kt
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationPresenter.kt
@@ -9,17 +9,22 @@ import android.content.Context
import android.content.Intent
import android.net.Uri
import android.os.Build
+import androidx.core.app.NotificationCompat
+import androidx.core.app.Person
import net.awan.pipelines_app.MainActivity
import net.awan.pipelines_app.R
/**
- * Posts server notifications in the system tray: one channel per kind and
- * priority (created lazily, grouped by kind), Android groups by the server's
- * `group`, a tap opens the app at the `click` deep link, and a dismissal is
- * reported back so the server clears it everywhere.
+ * Posts server notifications in the system tray. Each chat or run is one
+ * conversation notification (a MessagingStyle thread with the latest lines and
+ * the unread count), keyed by its server group. Thread notifications share a
+ * group per namespace, so Android bundles them under a summary ("N chats",
+ * "N runs"). A tap opens the app at the `click` deep link and clears the
+ * thread; a dismissal is reported back so the server clears it everywhere.
*/
class NotificationPresenter(private val context: Context) {
private val manager = context.getSystemService(NotificationManager::class.java)
+ private val history = ThreadHistory(ServiceSettings(context))
fun connectionNotification(status: DeliveryStatus): Notification {
ensureChannel(CONNECTION_CHANNEL, "Connection", NotificationManager.IMPORTANCE_MIN, null)
@@ -27,22 +32,17 @@ class NotificationPresenter(private val context: Context) {
DeliveryStatus.CONNECTED -> "Pipelines is connected"
DeliveryStatus.WAITING_FOR_NETWORK -> "Pipelines is waiting for a network"
DeliveryStatus.CONNECTING -> "Pipelines is connecting…"
+ DeliveryStatus.SIGN_IN_REQUIRED -> "Pipelines needs you to sign in"
else -> "Pipelines is reconnecting…"
}
- val open = PendingIntent.getActivity(
- context,
- 0,
- Intent(context, MainActivity::class.java).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK),
- PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
- )
return builder(CONNECTION_CHANNEL)
.setSmallIcon(R.drawable.ic_stat_pipelines)
.setContentTitle(text)
.setContentText("Delivering notifications from your server")
.setOngoing(true)
.setShowWhen(false)
- .setContentIntent(open)
- .setCategory(Notification.CATEGORY_SERVICE)
+ .setContentIntent(openApp())
+ .setCategory(NotificationCompat.CATEGORY_SERVICE)
.build()
}
@@ -50,86 +50,167 @@ class NotificationPresenter(private val context: Context) {
manager.notify(CONNECTION_ID, connectionNotification(status))
}
- fun show(notification: ServerNotification) {
- val id = DeliveryLedger.notificationId(notification.id)
- val channel = channelFor(notification)
- val title = notification.title.ifEmpty { "Pipelines" }
- val builder = builder(channel)
+ /** Posted when the server refuses the session; cleared once a connection opens. */
+ fun signInRequired() {
+ ensureChannel(ACCOUNT_CHANNEL, "Sign-in", NotificationManager.IMPORTANCE_DEFAULT, null)
+ val notification = builder(ACCOUNT_CHANNEL)
.setSmallIcon(R.drawable.ic_stat_pipelines)
- .setContentTitle(title)
- .setContentText(notification.message)
- .setStyle(Notification.BigTextStyle().bigText(notification.message))
+ .setContentTitle("Sign in to Pipelines again to keep notifications")
+ .setContentText("Notifications are paused until you sign in.")
.setAutoCancel(true)
- .setContentIntent(openIntent(notification, id))
- .setDeleteIntent(dismissIntent(notification.id, id))
- createdMillis(notification.createdAt)?.let { builder.setWhen(it).setShowWhen(true) }
- if (notification.group.isNotEmpty()) builder.setGroup(notification.group)
- if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
- @Suppress("DEPRECATION")
- builder.setPriority(effectivePriority(notification.kind, notification.priority) - 3)
- }
- manager.notify(id, builder.build())
- if (notification.group.isNotEmpty()) updateSummary(notification.group, channel)
+ .setContentIntent(openApp())
+ .build()
+ manager.notify(SIGN_IN_ID, notification)
}
- /** Removes notifications cleared on this or another device. */
+ fun clearSignIn() {
+ manager.cancel(SIGN_IN_ID)
+ }
+
+ private fun openApp(): PendingIntent = PendingIntent.getActivity(
+ context,
+ 0,
+ Intent(context, MainActivity::class.java).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK),
+ PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+ )
+
+ /** A notification without a group is posted on its own; otherwise it joins its thread. */
+ fun show(notification: ServerNotification) {
+ if (notification.group.isEmpty()) return showAlone(notification)
+ val thread = notification.group
+ history.append(thread, NotificationThreads.entryOf(notification, System.currentTimeMillis()))
+ val channel = postThread(thread) ?: return
+ updateSummary(NotificationThreads.namespaceOf(thread), channel)
+ }
+
+ /** Removes notifications cleared on this or another device, updating their threads. */
fun cancel(ids: Collection) {
- val groups = mutableSetOf()
- val active = manager.activeNotifications
- for (id in ids) {
- val notificationId = DeliveryLedger.notificationId(id)
- active.firstOrNull { it.id == notificationId }?.notification?.group?.let(groups::add)
- manager.cancel(notificationId)
+ for (id in ids) manager.cancel(DeliveryLedger.notificationId(id))
+ val namespaces = mutableSetOf()
+ for (thread in history.remove(ids)) {
+ if (history.entries(thread).isEmpty()) manager.cancel(threadNotificationId(thread))
+ else postThread(thread)
+ namespaces.add(NotificationThreads.namespaceOf(thread))
}
- groups.forEach { updateSummary(it, null) }
+ namespaces.forEach { updateSummary(it, null) }
}
- /** Removes every server notification, keeping the connection one. */
+ /** Removes every server notification and thread, keeping the connection one. */
fun cancelAll() {
+ history.clear()
manager.activeNotifications
.filter { it.id != CONNECTION_ID }
.forEach { manager.cancel(it.tag, it.id) }
}
- private fun updateSummary(group: String, channel: String?) {
- val summaryId = DeliveryLedger.notificationId("group:$group")
- val members = manager.activeNotifications.count {
- it.notification.group == group && it.id != summaryId
+ private fun showAlone(notification: ServerNotification) {
+ val id = DeliveryLedger.notificationId(notification.id)
+ val channel = channelFor(notification.kind, notification.priority)
+ val title = notification.title.ifEmpty { "Pipelines" }
+ val builder = builder(channel)
+ .setSmallIcon(R.drawable.ic_stat_pipelines)
+ .setContentTitle(title)
+ .setContentText(notification.message)
+ .setStyle(NotificationCompat.BigTextStyle().bigText(notification.message))
+ .setAutoCancel(true)
+ .setContentIntent(openIntent(listOf(notification.id), notification.click, id))
+ .setDeleteIntent(dismissIntent(listOf(notification.id), id))
+ createdMillis(notification.createdAt)?.let { builder.setWhen(it).setShowWhen(true) }
+ applyLegacyPriority(builder, notification.kind, notification.priority)
+ manager.notify(id, builder.build())
+ }
+
+ /**
+ * Posts the thread's notification from its stored entries, so a restart or
+ * a partial clear rebuilds the same conversation. Returns the channel it
+ * used, or null when the thread has no entries left.
+ */
+ private fun postThread(thread: String): String? {
+ val entries = history.entries(thread)
+ val latest = entries.lastOrNull() ?: return null
+ val channel = channelFor(latest.kind, latest.priority)
+ val id = threadNotificationId(thread)
+ val ids = entries.map { it.id }
+ val builder = builder(channel)
+ .setSmallIcon(R.drawable.ic_stat_pipelines)
+ .setNumber(entries.size)
+ .setGroup(NotificationThreads.groupKey(NotificationThreads.namespaceOf(thread)))
+ .setAutoCancel(true)
+ .setWhen(latest.whenMillis)
+ .setShowWhen(true)
+ .setContentIntent(openIntent(ids, latest.click, id))
+ .setDeleteIntent(dismissIntent(ids, id))
+ builder.setStyle(conversationStyle(entries))
+ applyLegacyPriority(builder, latest.kind, latest.priority)
+ manager.notify(id, builder.build())
+ return channel
+ }
+
+ /**
+ * The shown lines of a thread, most recent last, as a messaging conversation.
+ * NotificationCompat renders it on every API level the app supports.
+ */
+ private fun conversationStyle(entries: List): NotificationCompat.MessagingStyle {
+ val style = NotificationCompat.MessagingStyle(Person.Builder().setName("You").build())
+ .setConversationTitle(entries.last().sender)
+ .setGroupConversation(false)
+ for (entry in entries.takeLast(SHOWN_LINES)) {
+ val sender = Person.Builder().setName(entry.sender).build()
+ style.addMessage(NotificationCompat.MessagingStyle.Message(entry.text, entry.whenMillis, sender))
}
+ return style
+ }
+
+ /**
+ * Posts the namespace's group summary when two or more of its threads are
+ * shown, and removes it otherwise. A null [channel] reuses the summary's own.
+ */
+ private fun updateSummary(namespace: String, channel: String?) {
+ val group = NotificationThreads.groupKey(namespace)
+ val summaryId = DeliveryLedger.notificationId("group:$group")
+ val active = manager.activeNotifications
+ val members = active.count { it.notification.group == group && it.id != summaryId }
if (members < 2) {
- if (members == 0) manager.cancel(summaryId)
+ manager.cancel(summaryId)
return
}
- val existing = manager.activeNotifications.firstOrNull { it.id == summaryId }
- val summaryChannel = channel ?: existing?.notification?.channelIdCompat() ?: return
+ val summaryChannel = channel
+ ?: active.firstOrNull { it.id == summaryId }?.notification?.channelIdCompat()
+ ?: return
manager.notify(
summaryId,
builder(summaryChannel)
.setSmallIcon(R.drawable.ic_stat_pipelines)
.setContentTitle("Pipelines")
- .setContentText("$members notifications")
+ .setContentText("$members $namespace")
.setGroup(group)
.setGroupSummary(true)
- .setGroupAlertBehavior(Notification.GROUP_ALERT_CHILDREN)
+ .setGroupAlertBehavior(NotificationCompat.GROUP_ALERT_CHILDREN)
.setAutoCancel(true)
.build(),
)
}
+ private fun threadNotificationId(thread: String): Int = DeliveryLedger.notificationId("thread:$thread")
+
private fun Notification.channelIdCompat(): String? =
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) channelId else CONNECTION_CHANNEL
- private fun openIntent(notification: ServerNotification, requestCode: Int): PendingIntent {
+ /**
+ * A tap opens the deep link and clears every id in [ids] (newline-separated
+ * in the extra), so the server marks the whole thread seen.
+ */
+ private fun openIntent(ids: List, click: String, requestCode: Int): PendingIntent {
val intent = Intent(context, MainActivity::class.java)
.addFlags(
Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP or
Intent.FLAG_ACTIVITY_CLEAR_TOP,
)
- .putExtra(EXTRA_NOTIFICATION_ID, notification.id)
+ .putExtra(EXTRA_NOTIFICATION_ID, ids.joinToString("\n"))
// Only the app's own links are routed; Flutter's deep-link handling
// turns pipelines://run/ and pipelines://chat/ into a route.
- val click = Uri.parse(notification.click)
- if (click.scheme == "pipelines") intent.setAction(Intent.ACTION_VIEW).setData(click)
+ val link = Uri.parse(click)
+ if (link.scheme == "pipelines") intent.setAction(Intent.ACTION_VIEW).setData(link)
return PendingIntent.getActivity(
context,
requestCode,
@@ -138,25 +219,31 @@ class NotificationPresenter(private val context: Context) {
)
}
- private fun dismissIntent(serverId: String, requestCode: Int): PendingIntent =
+ private fun dismissIntent(serverIds: List, requestCode: Int): PendingIntent =
PendingIntent.getBroadcast(
context,
requestCode,
Intent(context, NotificationDismissReceiver::class.java)
.setAction(NotificationDismissReceiver.ACTION)
- .putExtra(EXTRA_NOTIFICATION_ID, serverId),
+ .putExtra(EXTRA_NOTIFICATION_ID, serverIds.joinToString("\n")),
PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
)
- private fun channelFor(notification: ServerNotification): String {
- val kind = notification.kind.replace(Regex("[^A-Za-z0-9_.-]"), "_")
- val priority = effectivePriority(kind, notification.priority)
- val id = "pipelines.$kind.p$priority"
+ private fun applyLegacyPriority(builder: NotificationCompat.Builder, kind: String, priority: Int) {
+ if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
+ builder.setPriority(effectivePriority(kind, priority) - 3)
+ }
+ }
+
+ private fun channelFor(kind: String, priorityValue: Int): String {
+ val kindName = kind.replace(Regex("[^A-Za-z0-9_.-]"), "_")
+ val priority = effectivePriority(kindName, priorityValue)
+ val id = "pipelines.$kindName.p$priority"
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
- val groupId = "pipelines.kind.$kind"
- manager.createNotificationChannelGroup(NotificationChannelGroup(groupId, kindLabel(kind)))
- val name = if (priority == kindPriority(kind)) kindLabel(kind)
- else "${kindLabel(kind)} (${priorityLabel(priority)})"
+ val groupId = "pipelines.kind.$kindName"
+ manager.createNotificationChannelGroup(NotificationChannelGroup(groupId, kindLabel(kindName)))
+ val name = if (priority == kindPriority(kindName)) kindLabel(kindName)
+ else "${kindLabel(kindName)} (${priorityLabel(priority)})"
ensureChannel(id, name, importance(priority), groupId)
}
return id
@@ -174,15 +261,20 @@ class NotificationPresenter(private val context: Context) {
manager.createNotificationChannel(channel)
}
- @Suppress("DEPRECATION")
- private fun builder(channel: String): Notification.Builder =
- if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) Notification.Builder(context, channel)
- else Notification.Builder(context)
+ /** NotificationCompat ignores the channel below API 26, so one builder serves every level. */
+ private fun builder(channel: String): NotificationCompat.Builder =
+ NotificationCompat.Builder(context, channel)
companion object {
const val CONNECTION_ID = 1
const val CONNECTION_CHANNEL = "pipelines.connection"
+ /** The "sign in again" notice; ids up to RESERVED_IDS are the service's own. */
+ const val SIGN_IN_ID = 2
+ const val ACCOUNT_CHANNEL = "pipelines.account"
+ /** Holds the server id(s) a tap or dismissal clears, newline-separated. */
const val EXTRA_NOTIFICATION_ID = "net.awan.pipelines.notification_id"
+ /** Lines of a thread shown in its conversation; the unread count still counts all. */
+ const val SHOWN_LINES = 5
private val KIND_LABELS = mapOf(
"run_waiting" to "Run waiting for you",
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationService.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationService.kt
index 870bb358..a029db52 100644
--- a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationService.kt
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationService.kt
@@ -24,6 +24,10 @@ import java.util.concurrent.TimeUnit
* engine runs here. It subscribes with the replay cursor, posts each pushed
* notification, mirrors cross-device clears and sends the user's own clears.
*
+ * Reconnects are alarms (ReconnectAlarms), so they fire during Doze; a
+ * periodic NotificationWatchdog restarts the service if it is down. A refused
+ * session (HTTP 401/403) stops the retry loop until a fresh cookie arrives.
+ *
* All state is confined to [handler]'s thread; OkHttp and connectivity
* callbacks post onto it.
*/
@@ -31,6 +35,8 @@ class NotificationService : Service() {
private lateinit var settings: ServiceSettings
private lateinit var ledger: DeliveryLedger
private lateinit var presenter: NotificationPresenter
+ private lateinit var log: ConnectionLog
+ private lateinit var wakeLock: ConnectWakeLock
private lateinit var thread: HandlerThread
private lateinit var handler: Handler
private val client = OkHttpClient.Builder()
@@ -48,7 +54,8 @@ class NotificationService : Service() {
private var networkAvailable = true
private var currentNetwork: Network? = null
private var networkCallback: ConnectivityManager.NetworkCallback? = null
- private val reconnect = Runnable { connect() }
+ /** A reconnect alarm is pending for the socket that is down. */
+ private var reconnectPending = false
override fun onBind(intent: Intent?): IBinder? = null
@@ -57,6 +64,8 @@ class NotificationService : Service() {
settings = ServiceSettings(this)
ledger = DeliveryLedger(settings)
presenter = NotificationPresenter(this)
+ log = ConnectionLog(settings)
+ wakeLock = ConnectWakeLock(this)
thread = HandlerThread("pipelines-notifications").also { it.start() }
handler = Handler(thread.looper)
goForeground(DeliveryStatus.CONNECTING)
@@ -66,16 +75,36 @@ class NotificationService : Service() {
override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
val action = intent?.action
+ // Alarms and the watchdog may start the service from the background;
+ // it must be foreground promptly, so do that before queuing the work.
+ goForeground(settings.status.let { if (it == DeliveryStatus.OFF) DeliveryStatus.CONNECTING else it })
handler.post {
when {
!settings.enabled || !settings.configured -> stopEverything()
action == ACTION_FLUSH -> flushClears()
+ action == ACTION_WATCHDOG -> if (isDown()) {
+ log.record("watchdog_restart")
+ restart()
+ }
+ action == ACTION_RECONNECT -> if (socket == null && settings.status != DeliveryStatus.SIGN_IN_REQUIRED) connect()
action == ACTION_RESTART || socket == null -> restart()
}
}
return START_STICKY
}
+ /**
+ * The app was swiped away. The foreground service keeps running, so this
+ * only queues a watchdog check shortly after, in case the process is lost.
+ */
+ override fun onTaskRemoved(rootIntent: Intent?) {
+ log.record("task_removed")
+ if (settings.enabled && settings.configured) {
+ ReconnectAlarms.schedule(this, TASK_REMOVED_CHECK_MILLIS, ACTION_WATCHDOG)
+ }
+ super.onTaskRemoved(rootIntent)
+ }
+
override fun onDestroy() {
running = null
networkCallback?.let {
@@ -87,6 +116,7 @@ class NotificationService : Service() {
socket?.close(1000, "service stopped")
socket = null
}
+ wakeLock.release()
thread.quitSafely()
if (settings.status != DeliveryStatus.UNCONFIGURED) setStatus(DeliveryStatus.OFF, notify = false)
super.onDestroy()
@@ -109,22 +139,33 @@ class NotificationService : Service() {
generation++
socket?.close(1000, "disabled")
socket = null
+ cancelReconnect()
+ wakeLock.release()
+ log.record("stopped")
setStatus(if (settings.configured) DeliveryStatus.OFF else DeliveryStatus.UNCONFIGURED, notify = false)
stopForeground(STOP_FOREGROUND_REMOVE)
stopSelf()
}
+ /**
+ * Delivery is meant to be running but no socket is open or on its way.
+ * Waiting for the network and a refused session are deliberate states.
+ */
+ private fun isDown(): Boolean =
+ socket == null && !reconnectPending &&
+ settings.status != DeliveryStatus.SIGN_IN_REQUIRED &&
+ settings.status != DeliveryStatus.WAITING_FOR_NETWORK
+
/** Server changed, credentials changed, or the first start: reopen now. */
private fun restart() {
if (ledger.bindServer(settings.serverId)) presenter.cancelAll()
- handler.removeCallbacks(reconnect)
backoff.reset()
endpointIndex = 0
connect()
}
private fun connect() {
- handler.removeCallbacks(reconnect)
+ cancelReconnect()
generation++
socket?.cancel()
socket = null
@@ -139,9 +180,12 @@ class NotificationService : Service() {
}.build()
} catch (error: IllegalArgumentException) {
Log.w(TAG, "invalid endpoint $endpoint", error)
+ log.record("invalid_endpoint", endpoint)
return scheduleReconnect()
}
setStatus(if (backoff.attempt == 0) DeliveryStatus.CONNECTING else DeliveryStatus.RECONNECTING)
+ log.record("connecting", endpoint)
+ wakeLock.hold()
val current = generation
socket = client.newWebSocket(request, Listener(current))
}
@@ -151,15 +195,46 @@ class NotificationService : Service() {
socket?.cancel()
socket = null
subscribeId = null
- if (!networkAvailable) return setStatus(DeliveryStatus.WAITING_FOR_NETWORK)
+ wakeLock.release()
+ if (!networkAvailable) {
+ cancelReconnect()
+ return setStatus(DeliveryStatus.WAITING_FOR_NETWORK)
+ }
setStatus(DeliveryStatus.RECONNECTING)
// Rotate through the server's trusted aliases on each failure.
endpointIndex++
- handler.postDelayed(reconnect, backoff.next())
+ val delay = backoff.next()
+ reconnectPending = true
+ ReconnectAlarms.schedule(this, delay, ACTION_RECONNECT)
+ log.record("retry_scheduled", "in ${delay / 1000}s")
+ }
+
+ private fun cancelReconnect() {
+ reconnectPending = false
+ ReconnectAlarms.cancel(this, ACTION_RECONNECT)
+ }
+
+ /**
+ * The server refused the session cookie. Retrying cannot succeed, so the
+ * loop stops here; a fresh cookie from the app restarts it.
+ */
+ private fun signInRequired(code: Int) {
+ generation++
+ socket?.cancel()
+ socket = null
+ subscribeId = null
+ wakeLock.release()
+ cancelReconnect()
+ log.record("sign_in_required", "HTTP $code", code)
+ setStatus(DeliveryStatus.SIGN_IN_REQUIRED)
+ presenter.signInRequired()
}
private fun onOpen(webSocket: WebSocket) {
backoff.reset()
+ wakeLock.release()
+ presenter.clearSignIn()
+ log.record("connected")
val id = "notify-${++sequence}"
subscribeId = id
webSocket.send(NotificationProtocol.subscribe(id, ledger.cursor))
@@ -179,6 +254,7 @@ class NotificationService : Service() {
is NotificationFrame.Cleared -> presenter.cancel(frame.ids)
is NotificationFrame.Refused -> {
Log.w(TAG, "subscribe_notifications refused: ${frame.error}")
+ log.record("refused", "${frame.error}")
scheduleReconnect()
}
NotificationFrame.Ignored -> Unit
@@ -212,13 +288,16 @@ class NotificationService : Service() {
val previous = currentNetwork
currentNetwork = network
networkAvailable = true
+ log.record("network_available")
// A new default network invalidates the old socket's route;
// a returning network retries at once instead of waiting
- // out the backoff.
+ // out the backoff. A refused session waits for a cookie.
val moved = previous != null && previous != network
val idle = settings.status == DeliveryStatus.WAITING_FOR_NETWORK ||
settings.status == DeliveryStatus.RECONNECTING
- if (settings.configured && (moved || previous == null || idle)) {
+ if (settings.configured && settings.status != DeliveryStatus.SIGN_IN_REQUIRED &&
+ (moved || previous == null || idle)
+ ) {
backoff.reset()
connect()
}
@@ -230,6 +309,7 @@ class NotificationService : Service() {
if (network != currentNetwork) return@post
currentNetwork = null
networkAvailable = false
+ log.record("network_lost")
scheduleReconnect()
}
}
@@ -249,17 +329,27 @@ class NotificationService : Service() {
webSocket.close(1000, null)
}
- override fun onClosed(webSocket: WebSocket, code: Int, reason: String) = current { scheduleReconnect() }
- override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) = current {
- Log.i(TAG, "socket failed (${response?.code}): ${t.message}")
+ override fun onClosed(webSocket: WebSocket, code: Int, reason: String) = current {
+ log.record("closed", "close $code ${reason}".trim())
scheduleReconnect()
}
+
+ override fun onFailure(webSocket: WebSocket, t: Throwable, response: Response?) = current {
+ val code = response?.code
+ Log.i(TAG, "socket failed ($code): ${t.message}")
+ log.record("failed", t.message ?: t.javaClass.simpleName, code)
+ if (ReconnectPolicy.isAuthRejection(code) && code != null) signInRequired(code)
+ else scheduleReconnect()
+ }
}
companion object {
private const val TAG = "PipelinesNotify"
const val ACTION_RESTART = "net.awan.pipelines.notify.RESTART"
const val ACTION_FLUSH = "net.awan.pipelines.notify.FLUSH"
+ const val ACTION_RECONNECT = "net.awan.pipelines.notify.RECONNECT"
+ const val ACTION_WATCHDOG = "net.awan.pipelines.notify.WATCHDOG"
+ private const val TASK_REMOVED_CHECK_MILLIS = 2_000L
@Volatile
var running: NotificationService? = null
@@ -277,6 +367,7 @@ class NotificationService : Service() {
return try {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) context.startForegroundService(intent)
else context.startService(intent)
+ NotificationWatchdog.schedule(context)
true
} catch (error: Exception) {
// Android 12+ refuses a foreground start from some background
@@ -287,6 +378,9 @@ class NotificationService : Service() {
}
fun stop(context: Context) {
+ ReconnectAlarms.cancel(context, ACTION_RECONNECT)
+ ReconnectAlarms.cancel(context, ACTION_WATCHDOG)
+ NotificationWatchdog.cancel(context)
context.stopService(Intent(context, NotificationService::class.java))
}
}
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationServiceChannel.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationServiceChannel.kt
index 17da5587..ee862c0f 100644
--- a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationServiceChannel.kt
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationServiceChannel.kt
@@ -52,10 +52,9 @@ class NotificationServiceChannel(private val activity: Activity, messenger: Bina
return
}
val changed = settings.configure(serverId, endpoints, cookie)
- val running = NotificationService.running != null
- if (changed || !running) {
- NotificationService.start(activity, if (changed) NotificationService.ACTION_RESTART else null)
- }
+ // A null action still restarts a service whose socket is down,
+ // which is how a refused session resumes with a fresh cookie.
+ NotificationService.start(activity, if (changed) NotificationService.ACTION_RESTART else null)
result.success(status())
}
"setEnabled" -> {
@@ -69,6 +68,7 @@ class NotificationServiceChannel(private val activity: Activity, messenger: Bina
}
result.success(status())
}
+ "connectionEvents" -> result.success(connectionEvents())
"requestBatteryExemption" -> {
result.success(requestBatteryExemption())
}
@@ -92,6 +92,17 @@ class NotificationServiceChannel(private val activity: Activity, messenger: Bina
)
}
+ /** The last connection events, newest first, for Settings' diagnosis. */
+ private fun connectionEvents(): List> =
+ ConnectionLog(settings).entries().map { event ->
+ buildMap {
+ put("time", event.timeMillis)
+ put("event", event.event)
+ event.error?.let { put("error", it) }
+ event.code?.let { put("code", it) }
+ }
+ }
+
private fun batteryExempt(): Boolean =
activity.getSystemService(PowerManager::class.java).isIgnoringBatteryOptimizations(activity.packageName)
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationThreads.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationThreads.kt
new file mode 100644
index 00000000..dcbab0b5
--- /dev/null
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationThreads.kt
@@ -0,0 +1,167 @@
+package net.awan.pipelines_app.notify
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * One server notification kept as a message line in its thread (a chat or a
+ * run). [sender] names the line in the conversation view; [whenMillis] is the
+ * server's creation time, or the arrival time when the server sent none.
+ */
+data class ThreadEntry(
+ val id: String,
+ val kind: String,
+ val priority: Int,
+ val sender: String,
+ val text: String,
+ val click: String,
+ val whenMillis: Long,
+)
+
+/**
+ * The per-thread message history that rebuilds a thread's notification after a
+ * service restart. Keyed by the server's `group` (`chat:` or `run:`);
+ * the count of entries is the unread count. Both the entries per thread and
+ * the threads kept are bounded, oldest first, so the store cannot grow without
+ * limit. Threads are kept in most-recently-active order.
+ */
+class ThreadHistory(
+ private val store: LedgerStore,
+ private val maxEntries: Int = MAX_ENTRIES,
+ private val maxThreads: Int = MAX_THREADS,
+) {
+ /** The entries of [thread], oldest first; empty when the thread is unknown. */
+ fun entries(thread: String): List = load()[thread].orEmpty()
+
+ /** The thread holding [id], if any. */
+ fun threadOf(id: String): String? = load().entries.firstOrNull { (_, list) ->
+ list.any { it.id == id }
+ }?.key
+
+ /** Adds [entry] to the end of [thread], which becomes the most recent thread. */
+ fun append(thread: String, entry: ThreadEntry) {
+ val threads = load()
+ val list = threads.remove(thread).orEmpty().toMutableList()
+ list.add(entry)
+ while (list.size > maxEntries) list.removeAt(0)
+ threads[thread] = list
+ while (threads.size > maxThreads) threads.remove(threads.keys.first())
+ save(threads)
+ }
+
+ /**
+ * Removes the entries with [ids]. Returns the threads whose entries changed;
+ * a thread left empty is dropped from the store.
+ */
+ fun remove(ids: Collection): Set {
+ val wanted = ids.toSet()
+ val threads = load()
+ val touched = mutableSetOf()
+ for ((thread, list) in threads) {
+ if (list.removeAll { it.id in wanted }) touched.add(thread)
+ }
+ threads.entries.removeAll { it.value.isEmpty() }
+ if (touched.isNotEmpty()) save(threads)
+ return touched
+ }
+
+ /** Forgets every thread, for example when the server changes. */
+ fun clear() = store.putString(KEY, null)
+
+ private fun load(): LinkedHashMap> {
+ val threads = LinkedHashMap>()
+ val raw = store.getString(KEY) ?: return threads
+ try {
+ val array = JSONArray(raw)
+ for (index in 0 until array.length()) {
+ val thread = array.getJSONObject(index)
+ val entries = thread.getJSONArray("entries")
+ threads[thread.getString("thread")] = (0 until entries.length())
+ .map { entryFrom(entries.getJSONObject(it)) }
+ .toMutableList()
+ }
+ } catch (_: Exception) {
+ // A corrupt store starts again empty rather than failing every post.
+ threads.clear()
+ }
+ return threads
+ }
+
+ private fun save(threads: Map>) {
+ if (threads.isEmpty()) return store.putString(KEY, null)
+ val array = JSONArray()
+ for ((thread, list) in threads) {
+ array.put(
+ JSONObject()
+ .put("thread", thread)
+ .put("entries", JSONArray(list.map(::entryJson))),
+ )
+ }
+ store.putString(KEY, array.toString())
+ }
+
+ private fun entryJson(entry: ThreadEntry): JSONObject = JSONObject()
+ .put("id", entry.id)
+ .put("kind", entry.kind)
+ .put("priority", entry.priority)
+ .put("sender", entry.sender)
+ .put("text", entry.text)
+ .put("click", entry.click)
+ .put("whenMillis", entry.whenMillis)
+
+ private fun entryFrom(json: JSONObject) = ThreadEntry(
+ id = json.optString("id"),
+ kind = json.optString("kind"),
+ priority = json.optInt("priority", 3),
+ sender = json.optString("sender"),
+ text = json.optString("text"),
+ click = json.optString("click"),
+ whenMillis = json.optLong("whenMillis"),
+ )
+
+ companion object {
+ const val KEY = "threads.history"
+ /** Unread entries kept per thread; the count shown is at most this. */
+ const val MAX_ENTRIES = 100
+ /** Threads kept; the oldest thread is forgotten first. */
+ const val MAX_THREADS = 50
+ }
+}
+
+/** Naming rules for threads, shared by the presenter and its tests. */
+object NotificationThreads {
+ /** `chat:` and `run:` map to their own group; any other group is generic. */
+ fun namespaceOf(group: String): String = when (group.substringBefore(':')) {
+ "chat" -> "chats"
+ "run" -> "runs"
+ else -> "notifications"
+ }
+
+ /** The Android group key that bundles one namespace's thread notifications. */
+ fun groupKey(namespace: String): String = "pipelines.$namespace"
+
+ /**
+ * The chat's own title. The server titles a chat question or approval
+ * " needs your answer" (or "... needs your approval"); the chat title
+ * is what names the message. Run titles are used as they are.
+ */
+ fun senderOf(kind: String, title: String): String {
+ val plain = title.trim()
+ if (!kind.startsWith("chat_")) return plain.ifEmpty { "Pipelines" }
+ return plain.removeSuffix(" needs your answer")
+ .removeSuffix(" needs your approval")
+ .trim()
+ .ifEmpty { "Chat" }
+ }
+
+ /** Builds the entry for a server notification that arrived at [receivedMillis]. */
+ fun entryOf(notification: ServerNotification, receivedMillis: Long): ThreadEntry = ThreadEntry(
+ id = notification.id,
+ kind = notification.kind,
+ priority = notification.priority,
+ sender = senderOf(notification.kind, notification.title),
+ text = notification.message.ifEmpty { notification.title },
+ click = notification.click,
+ whenMillis = NotificationPresenter.createdMillis(notification.createdAt) ?: receivedMillis,
+ )
+}
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationWatchdog.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationWatchdog.kt
new file mode 100644
index 00000000..7aa1f8ad
--- /dev/null
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/NotificationWatchdog.kt
@@ -0,0 +1,46 @@
+package net.awan.pipelines_app.notify
+
+import android.app.job.JobInfo
+import android.app.job.JobParameters
+import android.app.job.JobScheduler
+import android.app.job.JobService
+import android.content.ComponentName
+import android.content.Context
+
+/**
+ * A periodic check that the notification service is alive and connected while
+ * delivery is on. If the process was killed, or the socket is down with no
+ * reconnect pending, it starts the service again. JobScheduler defers jobs in
+ * Doze, so the reconnect alarms remain the primary path; this is the net under
+ * them.
+ */
+class NotificationWatchdog : JobService() {
+ override fun onStartJob(params: JobParameters?): Boolean {
+ val settings = ServiceSettings(this)
+ if (settings.enabled && settings.configured) {
+ NotificationService.start(this, NotificationService.ACTION_WATCHDOG)
+ }
+ return false
+ }
+
+ override fun onStopJob(params: JobParameters?): Boolean = true
+
+ companion object {
+ private const val JOB_ID = 4201
+ private const val PERIOD_MILLIS = 15 * 60_000L
+
+ fun schedule(context: Context) {
+ val scheduler = context.getSystemService(JobScheduler::class.java)
+ if (scheduler.getPendingJob(JOB_ID) != null) return
+ val job = JobInfo.Builder(JOB_ID, ComponentName(context, NotificationWatchdog::class.java))
+ .setPeriodic(PERIOD_MILLIS)
+ .setPersisted(true)
+ .build()
+ scheduler.schedule(job)
+ }
+
+ fun cancel(context: Context) {
+ context.getSystemService(JobScheduler::class.java).cancel(JOB_ID)
+ }
+ }
+}
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ReconnectAlarms.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ReconnectAlarms.kt
new file mode 100644
index 00000000..030a477b
--- /dev/null
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ReconnectAlarms.kt
@@ -0,0 +1,69 @@
+package net.awan.pipelines_app.notify
+
+import android.app.AlarmManager
+import android.app.PendingIntent
+import android.content.Context
+import android.content.Intent
+import android.os.Build
+import android.os.SystemClock
+
+/**
+ * Wakes the notification service when a reconnect, restart or watchdog check
+ * is due. A Handler delay pauses while the device dozes; an alarm does not.
+ * Each action has one pending alarm: scheduling again replaces it.
+ */
+object ReconnectAlarms {
+ fun schedule(context: Context, delayMillis: Long, action: String) {
+ val manager = context.getSystemService(AlarmManager::class.java)
+ val at = SystemClock.elapsedRealtime() + delayMillis
+ val pending = pendingFor(context, action)
+ val exact = ReconnectPolicy.alarmMode(exactPermitted(context)) ==
+ ReconnectPolicy.AlarmMode.EXACT_WHILE_IDLE
+ try {
+ if (exact) {
+ manager.setExactAndAllowWhileIdle(AlarmManager.ELAPSED_REALTIME_WAKEUP, at, pending)
+ } else {
+ manager.setAndAllowWhileIdle(AlarmManager.ELAPSED_REALTIME_WAKEUP, at, pending)
+ }
+ } catch (_: SecurityException) {
+ // The exact-alarm grant was revoked between the check and the call.
+ manager.setAndAllowWhileIdle(AlarmManager.ELAPSED_REALTIME_WAKEUP, at, pending)
+ }
+ }
+
+ fun cancel(context: Context, action: String) {
+ val existing = lookup(context, action) ?: return
+ context.getSystemService(AlarmManager::class.java).cancel(existing)
+ existing.cancel()
+ }
+
+ fun exactPermitted(context: Context): Boolean =
+ Build.VERSION.SDK_INT < Build.VERSION_CODES.S ||
+ context.getSystemService(AlarmManager::class.java).canScheduleExactAlarms()
+
+ /**
+ * Schedule and cancel must build the same kind of PendingIntent (a
+ * foreground-service one on Android 8+), or a cancel matches nothing.
+ * An alarm may start the service from the background; on Android 8+ that
+ * must be a foreground start, which the service then satisfies.
+ */
+ private fun pendingFor(context: Context, action: String): PendingIntent =
+ checkNotNull(build(context, action, PendingIntent.FLAG_UPDATE_CURRENT)) {
+ "FLAG_UPDATE_CURRENT always yields a PendingIntent"
+ }
+
+ private fun lookup(context: Context, action: String): PendingIntent? =
+ build(context, action, PendingIntent.FLAG_NO_CREATE)
+
+ private fun build(context: Context, action: String, mode: Int): PendingIntent? {
+ val intent = Intent(context, NotificationService::class.java).setAction(action)
+ val flags = PendingIntent.FLAG_IMMUTABLE or mode
+ return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+ PendingIntent.getForegroundService(context, requestCode(action), intent, flags)
+ } else {
+ PendingIntent.getService(context, requestCode(action), intent, flags)
+ }
+ }
+
+ private fun requestCode(action: String): Int = action.hashCode()
+}
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ReconnectPolicy.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ReconnectPolicy.kt
new file mode 100644
index 00000000..0d39ab97
--- /dev/null
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ReconnectPolicy.kt
@@ -0,0 +1,19 @@
+package net.awan.pipelines_app.notify
+
+/** Decisions the service makes on a failed socket, kept free of Android types. */
+object ReconnectPolicy {
+ /**
+ * HTTP 401/403 on the websocket handshake: the session cookie is no longer
+ * accepted. Retrying cannot succeed, so the service waits for a fresh cookie.
+ */
+ fun isAuthRejection(code: Int?): Boolean = code == 401 || code == 403
+
+ /**
+ * Exact alarms need SCHEDULE_EXACT_ALARM (Android 12+, user-revocable). When
+ * it is not granted the reconnect still fires during Doze, just inexactly.
+ */
+ fun alarmMode(exactPermitted: Boolean): AlarmMode =
+ if (exactPermitted) AlarmMode.EXACT_WHILE_IDLE else AlarmMode.WHILE_IDLE
+
+ enum class AlarmMode { EXACT_WHILE_IDLE, WHILE_IDLE }
+}
diff --git a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ServiceSettings.kt b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ServiceSettings.kt
index 08984eec..51003d1f 100644
--- a/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ServiceSettings.kt
+++ b/app/android/app/src/main/kotlin/net/awan/pipelines_app/notify/ServiceSettings.kt
@@ -11,6 +11,8 @@ enum class DeliveryStatus(val wire: String) {
CONNECTED("connected"),
RECONNECTING("reconnecting"),
WAITING_FOR_NETWORK("waiting_for_network"),
+ /** The server refused the session; delivery resumes when the app hands over a fresh cookie. */
+ SIGN_IN_REQUIRED("sign_in_required"),
}
/**
diff --git a/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ConnectionLogTest.kt b/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ConnectionLogTest.kt
new file mode 100644
index 00000000..efdd45ba
--- /dev/null
+++ b/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ConnectionLogTest.kt
@@ -0,0 +1,69 @@
+package net.awan.pipelines_app.notify
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class ConnectionLogTest {
+ private class MemoryStore : LedgerStore {
+ val values = mutableMapOf()
+ override fun getString(key: String) = values[key]
+ override fun putString(key: String, value: String?) {
+ if (value == null) values.remove(key) else values[key] = value
+ }
+ }
+
+ private class Clock(var now: Long = 1_000L) {
+ fun tick(): Long = now++
+ }
+
+ @Test
+ fun keepsTheLastFiftyEventsNewestFirst() {
+ val store = MemoryStore()
+ val clock = Clock()
+ val log = ConnectionLog(store, clock::tick)
+ repeat(ConnectionLog.CAPACITY + 10) { index -> log.record("event-$index") }
+ val entries = log.entries()
+ assertEquals(ConnectionLog.CAPACITY, entries.size)
+ assertEquals("event-59", entries.first().event)
+ assertEquals("event-10", entries.last().event)
+ }
+
+ @Test
+ fun errorAndCodeSurviveAReload() {
+ val store = MemoryStore()
+ ConnectionLog(store) { 42L }.record("failed", "Expected HTTP 101", 403)
+ val entry = ConnectionLog(store).entries().single()
+ assertEquals(42L, entry.timeMillis)
+ assertEquals("failed", entry.event)
+ assertEquals("Expected HTTP 101", entry.error)
+ assertEquals(403, entry.code)
+ }
+
+ @Test
+ fun eventsWithoutErrorOrCodeReadBackAsNull() {
+ val store = MemoryStore()
+ ConnectionLog(store).record("connected")
+ val entry = ConnectionLog(store).entries().single()
+ assertNull(entry.error)
+ assertNull(entry.code)
+ }
+
+ @Test
+ fun longErrorTextIsTrimmed() {
+ val store = MemoryStore()
+ ConnectionLog(store).record("failed", "x".repeat(500))
+ val error = ConnectionLog(store).entries().single().error!!
+ assertEquals(200, error.length)
+ }
+
+ @Test
+ fun corruptLogReadsAsEmptyInsteadOfThrowing() {
+ val store = MemoryStore()
+ store.values[ConnectionLog.KEY] = "not json"
+ assertTrue(ConnectionLog(store).entries().isEmpty())
+ ConnectionLog(store).record("connected")
+ assertEquals("connected", ConnectionLog(store).entries().single().event)
+ }
+}
diff --git a/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ReconnectPolicyTest.kt b/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ReconnectPolicyTest.kt
new file mode 100644
index 00000000..b78d1530
--- /dev/null
+++ b/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ReconnectPolicyTest.kt
@@ -0,0 +1,29 @@
+package net.awan.pipelines_app.notify
+
+import net.awan.pipelines_app.notify.ReconnectPolicy.AlarmMode
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class ReconnectPolicyTest {
+ @Test
+ fun http401And403StopTheRetryLoop() {
+ assertTrue(ReconnectPolicy.isAuthRejection(401))
+ assertTrue(ReconnectPolicy.isAuthRejection(403))
+ }
+
+ @Test
+ fun otherFailuresKeepRetrying() {
+ assertFalse(ReconnectPolicy.isAuthRejection(null))
+ assertFalse(ReconnectPolicy.isAuthRejection(500))
+ assertFalse(ReconnectPolicy.isAuthRejection(503))
+ assertFalse(ReconnectPolicy.isAuthRejection(404))
+ }
+
+ @Test
+ fun exactAlarmsWhenPermittedOtherwiseIdleTolerant() {
+ assertEquals(AlarmMode.EXACT_WHILE_IDLE, ReconnectPolicy.alarmMode(true))
+ assertEquals(AlarmMode.WHILE_IDLE, ReconnectPolicy.alarmMode(false))
+ }
+}
diff --git a/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ThreadHistoryTest.kt b/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ThreadHistoryTest.kt
new file mode 100644
index 00000000..a487acb0
--- /dev/null
+++ b/app/android/app/src/test/kotlin/net/awan/pipelines_app/notify/ThreadHistoryTest.kt
@@ -0,0 +1,118 @@
+package net.awan.pipelines_app.notify
+
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class ThreadHistoryTest {
+ private class MemoryStore : LedgerStore {
+ val values = mutableMapOf()
+ override fun getString(key: String) = values[key]
+ override fun putString(key: String, value: String?) {
+ if (value == null) values.remove(key) else values[key] = value
+ }
+ }
+
+ private fun entry(id: String, sender: String = "Chat A", text: String = "text $id") = ThreadEntry(
+ id = id,
+ kind = "chat_reply",
+ priority = 3,
+ sender = sender,
+ text = text,
+ click = "pipelines://chat/a",
+ whenMillis = 1_000L,
+ )
+
+ @Test
+ fun entriesAreKeptPerThreadInArrivalOrder() {
+ val history = ThreadHistory(MemoryStore())
+ history.append("chat:a", entry("1"))
+ history.append("run:7", entry("2"))
+ history.append("chat:a", entry("3"))
+ assertEquals(listOf("1", "3"), history.entries("chat:a").map { it.id })
+ assertEquals(listOf("2"), history.entries("run:7").map { it.id })
+ assertEquals("chat:a", history.threadOf("3"))
+ assertNull(history.threadOf("missing"))
+ }
+
+ @Test
+ fun entriesPerThreadAreBoundedOldestFirst() {
+ val history = ThreadHistory(MemoryStore(), maxEntries = 3)
+ (1..5).forEach { history.append("chat:a", entry("$it")) }
+ assertEquals(listOf("3", "4", "5"), history.entries("chat:a").map { it.id })
+ }
+
+ @Test
+ fun threadsAreBoundedAndTheOldestIsForgottenFirst() {
+ val history = ThreadHistory(MemoryStore(), maxThreads = 2)
+ history.append("chat:a", entry("1"))
+ history.append("chat:b", entry("2"))
+ history.append("chat:a", entry("3"))
+ history.append("chat:c", entry("4"))
+ assertTrue(history.entries("chat:b").isEmpty())
+ assertEquals(listOf("1", "3"), history.entries("chat:a").map { it.id })
+ assertEquals(listOf("4"), history.entries("chat:c").map { it.id })
+ }
+
+ @Test
+ fun historySurvivesANewInstanceOnTheSameStore() {
+ val store = MemoryStore()
+ ThreadHistory(store).append("chat:a", entry("1", sender = "Build bot", text = "done"))
+ val reopened = ThreadHistory(store).entries("chat:a")
+ assertEquals(1, reopened.size)
+ assertEquals("Build bot", reopened[0].sender)
+ assertEquals("done", reopened[0].text)
+ assertEquals("pipelines://chat/a", reopened[0].click)
+ assertEquals(1_000L, reopened[0].whenMillis)
+ }
+
+ @Test
+ fun corruptStoreStartsEmpty() {
+ val store = MemoryStore().apply { values[ThreadHistory.KEY] = "not json" }
+ val history = ThreadHistory(store)
+ assertTrue(history.entries("chat:a").isEmpty())
+ history.append("chat:a", entry("1"))
+ assertEquals(listOf("1"), history.entries("chat:a").map { it.id })
+ }
+
+ @Test
+ fun removeReturnsTouchedThreadsAndDropsEmptyOnes() {
+ val history = ThreadHistory(MemoryStore())
+ history.append("chat:a", entry("1"))
+ history.append("chat:a", entry("2"))
+ history.append("run:7", entry("3"))
+ val touched = history.remove(listOf("1", "3", "unknown"))
+ assertEquals(setOf("chat:a", "run:7"), touched)
+ assertEquals(listOf("2"), history.entries("chat:a").map { it.id })
+ assertTrue(history.entries("run:7").isEmpty())
+ assertEquals(emptySet(), history.remove(listOf("unknown")))
+ }
+
+ @Test
+ fun clearForgetsEveryThread() {
+ val store = MemoryStore()
+ val history = ThreadHistory(store)
+ history.append("chat:a", entry("1"))
+ history.clear()
+ assertTrue(history.entries("chat:a").isEmpty())
+ assertNull(store.getString(ThreadHistory.KEY))
+ }
+
+ @Test
+ fun chatTitlesDropTheQuestionSuffix() {
+ assertEquals("Deploy review", NotificationThreads.senderOf("chat_question", "Deploy review needs your answer"))
+ assertEquals("Deploy review", NotificationThreads.senderOf("chat_approval", "Deploy review needs your approval"))
+ assertEquals("Chat", NotificationThreads.senderOf("chat_question", "Chat needs your answer"))
+ assertEquals("Pipelines", NotificationThreads.senderOf("run_failed", " "))
+ assertEquals("Run needs your decision", NotificationThreads.senderOf("run_waiting", "Run needs your decision"))
+ }
+
+ @Test
+ fun namespacesSeparateChatsFromRuns() {
+ assertEquals("chats", NotificationThreads.namespaceOf("chat:s1"))
+ assertEquals("runs", NotificationThreads.namespaceOf("run:7"))
+ assertEquals("pipelines.chats", NotificationThreads.groupKey("chats"))
+ assertEquals("pipelines.runs", NotificationThreads.groupKey("runs"))
+ }
+}
diff --git a/app/lib/application/app_terminals.dart b/app/lib/application/app_terminals.dart
index 334ec583..5b3e9dc8 100644
--- a/app/lib/application/app_terminals.dart
+++ b/app/lib/application/app_terminals.dart
@@ -8,6 +8,7 @@ import '../features/terminal/terminal_machines.dart';
import '../features/terminal/terminal_surface.dart';
import '../features/terminal/terminal_toggle_button.dart';
import '../features/terminal/terminal_window.dart';
+import '../shell/list_detail_policy.dart';
import '../shell/windows/window_manager.dart';
/// The app's machine terminals: one hub over every connected machine (the
@@ -66,6 +67,14 @@ class AppTerminals {
/// The bar button showing or hiding the terminal.
Widget toggle() => TerminalToggleButton(layout: layout);
+ /// The Chat tab's shell-bar button. Only a wide layout shows the shell bar
+ /// over an open chat, so only there is it kept. A narrow layout has none:
+ /// its open chat's own bar carries the terminal (see
+ /// `terminalChatBarAction`), and a chat list's bar has none (the shortcut
+ /// still shows the terminal).
+ Widget? barToggle(BuildContext context) =>
+ showsListBesideDetail(context) ? toggle() : null;
+
void dispose() {
floating?.dispose();
hub.dispose();
diff --git a/app/lib/application/pipelines_app.dart b/app/lib/application/pipelines_app.dart
index 9e422c5f..2f30c46a 100644
--- a/app/lib/application/pipelines_app.dart
+++ b/app/lib/application/pipelines_app.dart
@@ -28,6 +28,8 @@ import '../features/runs/ui/run_search_selection.dart';
import '../features/search/domain/search_target.dart';
import '../features/settings/settings_screen.dart';
import '../features/settings/settings_store.dart';
+import '../features/walkthrough/walkthrough_gate.dart';
+import '../features/walkthrough/walkthrough_store.dart';
import '../features/updates/app_updates.dart';
import '../features/updates/launch_update.dart';
import '../features/updates/launch_update_dialog.dart';
@@ -579,6 +581,10 @@ class _PipelinesAppState extends State
_attentionCount.value = count;
}
+ /// The device's first-run walkthrough record (per device, not per server).
+ final WalkthroughStore _walkthroughStore =
+ const SharedPreferencesWalkthroughStore();
+
@override
Widget build(BuildContext context) => widget.servers == null
? MyApp.router(routerConfig: _config)
@@ -810,7 +816,7 @@ class _PipelinesAppState extends State
builder: (context, count, _) => _terminals.surround(
_shellFor(route, count),
onChat: route.kind == AppRouteKind.chat,
- windows: WindowHost(manager: _windows),
+ windows: WindowHost(manager: _windows, reservesRail: true),
),
);
@@ -829,13 +835,14 @@ class _PipelinesAppState extends State
final runsRoute = tab(AppDestination.runs);
final chatRoute = tab(AppDestination.chat);
return AdaptiveShell(
- // The terminal button sits on the Chat tab only; the keyboard
+ // The terminal button sits on the Chat tab's shell bar on wide layouts;
+ // a narrow layout has it in the chat's own bar instead. The keyboard
// shortcut still toggles the terminal everywhere.
barActions: [
// Shown on every tab while the app has floating windows.
WindowsMenuButton(manager: _windows),
if (_destinationOf(route.kind) == AppDestination.chat)
- _terminals.toggle(),
+ ?_terminals.barToggle(context),
],
attentionCount: counts.attention,
runningRunCount: counts.running,
@@ -847,32 +854,40 @@ class _PipelinesAppState extends State
_bodyRoutes[AppDestination.pipelines] ?? AppRoute.pipelines,
),
destinationBodies: {
- AppDestination.pipelines: (_) => PipelinesDestination(
- session: _session,
- server: widget.server,
- active: _destinationOf(route.kind) == AppDestination.pipelines,
- legacyPendingEndpoints: widget.legacyPendingEndpoints,
- refreshToken: _pipelinesRefresh,
- onRunStarted: _runStarted,
- onViewPipelineRuns: (id) =>
- _delegate.goTo(AppRoute.runsForPipeline(id)),
- onOpenSchedules: _delegate.openSchedules,
- onOpenSettings: () => _delegate.goTo(AppRoute.settings),
- // The open pipeline is part of the route, so Back steps out of it.
- onSelectionChanged: (id) {
- final current = _delegate.route;
- if (current.kind != AppRouteKind.pipelines) return;
- if (id == null) {
- if (current.pipelineId != null) {
- _delegate.goTo(AppRoute.pipelines);
+ AppDestination.pipelines: (_) => FirstRunWalkthroughGate(
+ store: _walkthroughStore,
+ enabled: _destinationOf(route.kind) == AppDestination.pipelines,
+ serverScope: _navigationScope,
+ connection: _session,
+ connected: () => _session.connected,
+ gateway: _session.client,
+ child: PipelinesDestination(
+ session: _session,
+ server: widget.server,
+ active: _destinationOf(route.kind) == AppDestination.pipelines,
+ legacyPendingEndpoints: widget.legacyPendingEndpoints,
+ refreshToken: _pipelinesRefresh,
+ onRunStarted: _runStarted,
+ onViewPipelineRuns: (id) =>
+ _delegate.goTo(AppRoute.runsForPipeline(id)),
+ onOpenSchedules: _delegate.openSchedules,
+ onOpenSettings: () => _delegate.goTo(AppRoute.settings),
+ // The open pipeline is part of the route, so Back steps out of it.
+ onSelectionChanged: (id) {
+ final current = _delegate.route;
+ if (current.kind != AppRouteKind.pipelines) return;
+ if (id == null) {
+ if (current.pipelineId != null) {
+ _delegate.goTo(AppRoute.pipelines);
+ }
+ } else if (current.pipelineId != id) {
+ _delegate.goTo(AppRoute.pipeline(id));
}
- } else if (current.pipelineId != id) {
- _delegate.goTo(AppRoute.pipeline(id));
- }
- },
- initialPipelineId: pipelinesRoute.pipelineId,
- initialVersion: pipelinesRoute.version,
- initialStageKey: pipelinesRoute.stageKey,
+ },
+ initialPipelineId: pipelinesRoute.pipelineId,
+ initialVersion: pipelinesRoute.version,
+ initialStageKey: pipelinesRoute.stageKey,
+ ),
),
// The one place a field or artifact hit's selection can be resolved: the
// run detail owns the recorded visit and Summary section.
diff --git a/app/lib/features/chat/chat_screen_keys.dart b/app/lib/features/chat/chat_screen_keys.dart
index 7a3a51ca..d19d6e75 100644
--- a/app/lib/features/chat/chat_screen_keys.dart
+++ b/app/lib/features/chat/chat_screen_keys.dart
@@ -1,54 +1,11 @@
part of 'screen.dart';
-/// How many chats the visit remembers for Ctrl+Tab over a single pane.
-const chatRecentSessionLimit = 8;
-
/// Keys the Chat destination answers from anywhere in it, also while the
/// sidebar or a toolbar owns focus: a bare `/` puts the keyboard in the open
-/// chat's composer, and Ctrl+Tab over a single pane returns to the chat shown
-/// before it (and back again). Both are handled before the focus tree, like
-/// the workspace's pane cycling, and leave other destinations, popups,
-/// dialogs and any focused text field alone.
+/// chat's composer. It is handled before the focus tree, like the workspace's
+/// pane cycling, and leaves other destinations, popups, dialogs and any
+/// focused text field alone.
mixin _ChatScreenKeys on State, _ChatScreenWorkspace {
- void _open(JsonMap session, {bool focusComposer});
-
- /// The chats this visit has shown in the workspace, most recent first; the
- /// active one leads it. In memory only: a reopened app starts afresh.
- final List _recentSessions = [];
-
- /// Moves the active pane's chat to the front. Called on every workspace
- /// change, including a restored layout, so the chat opened before the
- /// current one is always the second entry.
- @override
- void _noteRecentSession() {
- final id = _workspace.activePane?.sessionId;
- if (id == null || id.isEmpty || _recentSessions.firstOrNull == id) return;
- _recentSessions
- ..remove(id)
- ..insert(0, id);
- if (_recentSessions.length > chatRecentSessionLimit) {
- _recentSessions.removeLast();
- }
- }
-
- /// Drops [id]: a closed chat, or one `/new` moved to a fresh session.
- void _forgetRecentSession(String id) => _recentSessions.remove(id);
-
- /// Drops every remembered chat: ids belong to one server.
- @override
- void _forgetRecentSessions() => _recentSessions.clear();
-
- /// Over a single pane, opens the chat shown before the active one with its
- /// composer focused; false when this visit has shown no other chat.
- @override
- bool _toggleRecentChat() {
- final current = _workspace.activePane?.sessionId;
- final previous = _recentSessions.where((id) => id != current).firstOrNull;
- if (previous == null) return false;
- _open(_rowFor(previous) ?? {'id': previous}, focusComposer: true);
- return true;
- }
-
/// Whether the shown destination is Chat with no popup, dialog or other
/// route over it, so a key pressed now is meant for the open chat.
@override
diff --git a/app/lib/features/chat/chat_screen_workspace.dart b/app/lib/features/chat/chat_screen_workspace.dart
index edd24e01..faf1f847 100644
--- a/app/lib/features/chat/chat_screen_workspace.dart
+++ b/app/lib/features/chat/chat_screen_workspace.dart
@@ -5,9 +5,6 @@ mixin _ChatScreenWorkspace on State {
Map get _openedSessions;
ChatComposerFocusRequests get _composerFocus;
bool _chatOwnsKeyboard();
- bool _toggleRecentChat();
- void _noteRecentSession();
- void _forgetRecentSessions();
JsonMap? _rowFor(String id);
void _back();
bool get _pageOpen;
@@ -130,7 +127,6 @@ mixin _ChatScreenWorkspace on State {
_workspaceBinding = null;
if (_workspaceScope != null && scope != _workspaceScope) {
_workspace.restoreLayout(ChatWorkspaceSnapshot.fromLayout(null, null)!);
- _forgetRecentSessions();
_workspaceVisible = false;
_usedWorkspace = true;
_sidebarMode = ChatSidebarMode.expanded;
@@ -152,29 +148,29 @@ mixin _ChatScreenWorkspace on State {
String? _publishedWorkspaceSession;
String _workspaceSignature = '';
- /// Ctrl+Tab cycles retained panes even when the sidebar or toolbar owns
- /// focus. Over a single pane it swaps in the chat shown before this one
- /// instead, and back again (see [_toggleRecentChat]). Command+Tab stays
- /// with the operating system's application switcher. While the app's
- /// terminal is shown, Ctrl+Tab moves between its tabs instead. While a
- /// floating chat window holds the keyboard, Ctrl+Tab cycles those windows
- /// (see [ChatWindows]).
+ /// Ctrl+Tab cycles the floating chat windows while any is shown, from the
+ /// tiling as well (see [ChatWindows]). With none shown it cycles the
+ /// retained panes, even when the sidebar or toolbar owns focus, and over a
+ /// single pane it does nothing: it never brings up a chat that is not
+ /// visible in the tiling. Command+Tab stays with the operating system's
+ /// application switcher. While the app's terminal is shown, Ctrl+Tab moves
+ /// between its tabs instead. A floating window that is not a chat, or any
+ /// other window holding the keyboard, keeps the key.
bool _cycleChatKey(KeyEvent event) {
final keyboard = HardwareKeyboard.instance;
if (event is! KeyDownEvent ||
TerminalScope.peek(context)?.claimsTabKeys == true ||
- keyboardWindow()?.entry.kind == chatWindowKind ||
+ keyboardWindow() != null ||
event.logicalKey != LogicalKeyboardKey.tab ||
!keyboard.isControlPressed ||
keyboard.isMetaPressed ||
keyboard.isAltPressed ||
- !_workspaceVisible ||
- _workspace.paneCount == 0 ||
!_chatOwnsKeyboard()) {
return false;
}
+ if (widget.windows?.raiseTopFromTiling() ?? false) return true;
+ if (!_workspaceVisible || _workspace.paneCount < 2) return false;
final panes = _workspace.panes;
- if (panes.length == 1 && _toggleRecentChat()) return true;
final active = panes.indexWhere(
(pane) => pane.id == _workspace.activePaneId,
);
@@ -199,7 +195,6 @@ mixin _ChatScreenWorkspace on State {
void _workspaceChanged() {
if (!mounted) return;
- _noteRecentSession();
if (_workspaceBinding?.isRestoring == true) return;
final signature =
'${_workspace.activePaneId}:${_workspace.panes.map((p) => '${p.id}=${p.sessionId}').join(',')}';
diff --git a/app/lib/features/chat/conversation/chat_thread_view.dart b/app/lib/features/chat/conversation/chat_thread_view.dart
index 463a7dc2..023d11ff 100644
--- a/app/lib/features/chat/conversation/chat_thread_view.dart
+++ b/app/lib/features/chat/conversation/chat_thread_view.dart
@@ -1476,6 +1476,9 @@ class _ChatThreadViewState extends State {
onPressed: _toggleFiles,
materialIcon: _filesVisible ? Icons.folder : Icons.folder_outlined,
),
+ // A narrow layout's terminal button, beside Files; wide keeps the
+ // shell bar's.
+ ?terminalChatBarAction(context),
],
moreActions: [
?widget.sidebarControl,
diff --git a/app/lib/features/chat/screen.dart b/app/lib/features/chat/screen.dart
index 3d723db4..1cb25567 100644
--- a/app/lib/features/chat/screen.dart
+++ b/app/lib/features/chat/screen.dart
@@ -159,7 +159,6 @@ class _ChatScreenState extends State
_workspace.open(initial);
_workspaceVisible = true;
_publishedWorkspaceSession = initial;
- _noteRecentSession();
}
_workspace.addListener(_workspaceChanged);
_bindWorkspacePersistence();
@@ -238,7 +237,6 @@ class _ChatScreenState extends State
void _openBySelection(JsonMap session) =>
_open(session, focusComposer: chatSelectionFocusesComposer(session));
- @override
void _open(JsonMap session, {bool focusComposer = false}) {
final id = '${session['id'] ?? ''}';
if (id.isEmpty) return;
@@ -285,7 +283,6 @@ class _ChatScreenState extends State
/// A model switch accepted here in this visit moved with the chat.
void _followNewSession(String previousId, JsonMap session, String notice) {
_runtime.movedToSession(previousId, session, notice);
- _forgetRecentSession(previousId);
_workspace.replaceSession(previousId, '${session['id'] ?? ''}');
if (_workspace.paneCount == 0) _open(session);
}
@@ -293,7 +290,6 @@ class _ChatScreenState extends State
/// `/close` was accepted: the conversation leaves, back to the list, which
/// re-reads the closed row.
void _closed(String sessionId) {
- _forgetRecentSession(sessionId);
for (final pane
in _workspace.panes
.where((pane) => pane.sessionId == sessionId)
diff --git a/app/lib/features/chat/windows/chat_windows.dart b/app/lib/features/chat/windows/chat_windows.dart
index c2c7fb59..683332d7 100644
--- a/app/lib/features/chat/windows/chat_windows.dart
+++ b/app/lib/features/chat/windows/chat_windows.dart
@@ -194,6 +194,7 @@ class ChatWindows {
/// session list, which nothing else reads while the Chat destination is
/// not built.
void _rowsChanged() {
+ _noteOpenOrder();
final ids = {for (final w in windows) w.contentId};
if (ids.isEmpty || !ready) return;
final sessions = runtime.sessions;
@@ -232,7 +233,7 @@ class ChatWindows {
}
/// Ctrl+Tab and Ctrl+Shift+Tab while a floating chat window holds the
- /// keyboard: the next (previous) visible chat window, in stacking order and
+ /// keyboard: the next (previous) shown chat window, in open order and
/// wrapping, comes to the top. The window host then gives it the keyboard,
/// its composer. Left alone when another window or the tiling has the
/// keyboard, when the terminal claims tab keys, or with one window.
@@ -245,16 +246,47 @@ class ChatWindows {
_terminalClaimsTabs()) {
return KeyEventResult.ignored;
}
- final target = chatWindowAfter(
- windows.where(manager.isVisible).toList(),
- scope.entry.id,
- step,
- );
+ final target = chatWindowAfter(shownInOpenOrder(), scope.entry.id, step);
if (target == null) return KeyEventResult.ignored;
manager.raise(target.id);
return KeyEventResult.handled;
}
+ /// The ids of the chat windows in the order they were opened; a window
+ /// restored from a saved layout keeps its saved place. Raising a window
+ /// changes the stacking order, not this one, so the Ctrl+Tab cycle is
+ /// stable. Kept in step on every change of the windows (see [_rowsChanged]).
+ final List _openOrder = [];
+
+ void _noteOpenOrder() {
+ final ids = {for (final w in windows) w.id};
+ _openOrder.removeWhere((id) => !ids.contains(id));
+ for (final w in windows) {
+ if (!_openOrder.contains(w.id)) _openOrder.add(w.id);
+ }
+ }
+
+ /// The shown chat windows (not minimised, their group shown), in open order.
+ List shownInOpenOrder() {
+ _noteOpenOrder();
+ final shown = {
+ for (final w in windows)
+ if (manager.isVisible(w)) w.id: w,
+ };
+ return [for (final id in _openOrder) ?shown[id]];
+ }
+
+ /// Ctrl+Tab from the tiling or the chat list while chat windows are shown:
+ /// the top-most shown chat window comes to the top and its composer takes
+ /// the keyboard. False, doing nothing, when no chat window is shown.
+ bool raiseTopFromTiling() {
+ final top = windows.where(manager.isVisible).lastOrNull;
+ if (top == null) return false;
+ manager.raise(top.id);
+ kind.focusContent(top);
+ return true;
+ }
+
bool _terminalClaimsTabs() {
final context = FocusManager.instance.primaryFocus?.context;
return context != null &&
diff --git a/app/lib/features/notification_service/notification_service_bridge.dart b/app/lib/features/notification_service/notification_service_bridge.dart
index 18dc289b..fa0f284d 100644
--- a/app/lib/features/notification_service/notification_service_bridge.dart
+++ b/app/lib/features/notification_service/notification_service_bridge.dart
@@ -4,8 +4,10 @@ import 'package:flutter/foundation.dart';
import 'package:flutter/services.dart';
import 'host_platform_stub.dart' if (dart.library.io) 'host_platform_io.dart';
+import 'notification_service_events.dart';
import 'notification_service_status.dart';
+export 'notification_service_events.dart';
export 'notification_service_status.dart';
/// The app's handle on Android background delivery: a native foreground
@@ -35,6 +37,9 @@ abstract interface class NotificationServiceBridge {
/// Opens Android's "ignore battery optimisations" prompt.
Future requestBatteryExemption();
+
+ /// The service's recent connection events, newest first (at most 50).
+ Future> connectionEvents();
}
/// The bridge for this platform. One instance owns the channel's handler.
@@ -104,6 +109,16 @@ class MethodChannelNotificationServiceBridge
@override
Future requestBatteryExemption() async =>
await _channel.invokeMethod('requestBatteryExemption') ?? false;
+
+ @override
+ Future> connectionEvents() async {
+ final reply = await _channel.invokeListMethod('connectionEvents');
+ return [
+ for (final item in reply ?? const [])
+ if (item is Map)
+ NotificationConnectionEvent.fromMap(item),
+ ];
+ }
}
/// Web, iOS and desktop: no background service; nothing is pretended.
@@ -136,4 +151,8 @@ class UnsupportedNotificationServiceBridge
@override
Future requestBatteryExemption() async => false;
+
+ @override
+ Future> connectionEvents() async =>
+ const [];
}
diff --git a/app/lib/features/notification_service/notification_service_controller.dart b/app/lib/features/notification_service/notification_service_controller.dart
index 711e6a53..310ece5d 100644
--- a/app/lib/features/notification_service/notification_service_controller.dart
+++ b/app/lib/features/notification_service/notification_service_controller.dart
@@ -21,22 +21,52 @@ class NotificationServiceController extends ChangeNotifier {
late final StreamSubscription _changes;
NotificationServiceStatus? _status;
+ List _events = const [];
bool _busy = false;
String _error = '';
bool _disposed = false;
NotificationServiceStatus? get status => _status;
+
+ /// The service's connection log, newest first.
+ List get events => _events;
bool get busy => _busy;
String get error => _error;
+ bool _askedForExemption = false;
+
Future load() => _run(bridge.status);
+ /// Opens Settings: reads the status and, when delivery is already on but the
+ /// battery exemption is missing (existing users, upgrades), asks for it once
+ /// per controller. The warning row stays if the prompt is declined.
+ Future open() async {
+ await load();
+ final current = _status;
+ if (current != null &&
+ current.enabled &&
+ !current.batteryExempt &&
+ !_askedForExemption) {
+ _askedForExemption = true;
+ await allowBackgroundDelivery();
+ }
+ }
+
/// Re-reads after returning from a system screen (permission, battery).
+ /// Never prompts again: a declined prompt is shown as the warning row.
Future refresh() => load();
+ /// Switching delivery on first asks for the battery exemption, so the
+ /// service starts with the prompt answered: delivery should not pause while
+ /// the phone is idle.
Future setEnabled(bool enabled) => _run(() async {
- if (enabled && _status?.notificationsAllowed == false) {
- await requestNotificationPermission?.call();
+ if (enabled) {
+ if (_status?.notificationsAllowed == false) {
+ await requestNotificationPermission?.call();
+ }
+ if (_status?.batteryExempt == false) {
+ await bridge.requestBatteryExemption();
+ }
}
return bridge.setEnabled(enabled);
});
@@ -58,6 +88,7 @@ class NotificationServiceController extends ChangeNotifier {
_notify();
try {
_status = await action();
+ _events = await bridge.connectionEvents();
} catch (error) {
_error = 'Background delivery is unavailable: $error';
} finally {
@@ -69,6 +100,17 @@ class NotificationServiceController extends ChangeNotifier {
void _apply(NotificationServiceStatus status) {
_status = status;
_notify();
+ // The service logs its own transitions; re-read so the log stays current.
+ unawaited(_refreshEvents());
+ }
+
+ Future _refreshEvents() async {
+ try {
+ _events = await bridge.connectionEvents();
+ } catch (error) {
+ _error = 'Background delivery is unavailable: $error';
+ }
+ _notify();
}
void _notify() {
diff --git a/app/lib/features/notification_service/notification_service_events.dart b/app/lib/features/notification_service/notification_service_events.dart
new file mode 100644
index 00000000..3afd2fa3
--- /dev/null
+++ b/app/lib/features/notification_service/notification_service_events.dart
@@ -0,0 +1,64 @@
+/// One entry of the background service's connection log, as Settings shows
+/// it for diagnosis. The service keeps the newest events first.
+class NotificationConnectionEvent {
+ const NotificationConnectionEvent({
+ required this.time,
+ required this.event,
+ this.error,
+ this.code,
+ });
+
+ final DateTime time;
+
+ /// The service's wire name for what happened, e.g. `failed`.
+ final String event;
+ final String? error;
+
+ /// The HTTP status of a failed handshake, when there was one.
+ final int? code;
+
+ factory NotificationConnectionEvent.fromMap(Map map) =>
+ NotificationConnectionEvent(
+ time: DateTime.fromMillisecondsSinceEpoch(
+ (map['time'] as num?)?.toInt() ?? 0,
+ ),
+ event: map['event'] as String? ?? 'unknown',
+ error: map['error'] as String?,
+ code: (map['code'] as num?)?.toInt(),
+ );
+
+ /// A short, plain name for the event.
+ String get title => switch (event) {
+ 'connecting' => 'Opening socket',
+ 'connected' => 'Socket opened',
+ 'closed' => 'Socket closed',
+ 'failed' => 'Socket failed',
+ 'retry_scheduled' => 'Retry scheduled',
+ 'sign_in_required' => 'Session refused',
+ 'refused' => 'Subscribe refused',
+ 'network_available' => 'Network available',
+ 'network_lost' => 'Network lost',
+ 'invalid_endpoint' => 'Invalid address',
+ 'watchdog_restart' => 'Watchdog restart',
+ 'task_removed' => 'App closed from recents',
+ 'stopped' => 'Stopped',
+ _ => event,
+ };
+
+ /// The HTTP code and error text, when there are any.
+ String? get detail {
+ final parts = [
+ if (code != null) 'HTTP $code',
+ if (error != null && error!.isNotEmpty) error!,
+ ];
+ return parts.isEmpty ? null : parts.join(' · ');
+ }
+
+ /// Local time as `MM-DD HH:MM:SS`.
+ String get timeLabel {
+ String two(int value) => value.toString().padLeft(2, '0');
+ final local = time.toLocal();
+ return '${two(local.month)}-${two(local.day)} '
+ '${two(local.hour)}:${two(local.minute)}:${two(local.second)}';
+ }
+}
diff --git a/app/lib/features/notification_service/notification_service_status.dart b/app/lib/features/notification_service/notification_service_status.dart
index d44d09e7..f1f1c3bf 100644
--- a/app/lib/features/notification_service/notification_service_status.dart
+++ b/app/lib/features/notification_service/notification_service_status.dart
@@ -5,7 +5,8 @@ enum DeliveryState {
connecting('connecting'),
connected('connected'),
reconnecting('reconnecting'),
- waitingForNetwork('waiting_for_network');
+ waitingForNetwork('waiting_for_network'),
+ signInRequired('sign_in_required');
const DeliveryState(this.wire);
@@ -59,6 +60,8 @@ class NotificationServiceStatus {
DeliveryState.connecting => 'Connecting…',
DeliveryState.reconnecting => 'Reconnecting…',
DeliveryState.waitingForNetwork => 'Waiting for a network',
+ DeliveryState.signInRequired =>
+ 'Sign in to Pipelines again to keep notifications',
DeliveryState.unconfigured => 'Starts after the app connects to a server',
DeliveryState.off => enabled ? 'Not running' : 'Off',
};
diff --git a/app/lib/features/pipelines/screen.dart b/app/lib/features/pipelines/screen.dart
index f6a1a810..fb0ea904 100644
--- a/app/lib/features/pipelines/screen.dart
+++ b/app/lib/features/pipelines/screen.dart
@@ -2,6 +2,7 @@ import '../../ui/adaptive/segmented_bar.dart';
import '../../shell/destination.dart';
import '../../shell/detail_page.dart';
import '../../shell/list_detail.dart';
+import '../../shell/shell_rail_scope.dart';
import 'package:flutter/material.dart';
import '../../core/api_gateway.dart';
@@ -288,7 +289,10 @@ class _PipelinesScreenState extends State {
if (listShown && widget.onOpenSchedules != null)
_schedulesButton(context),
_refreshButton(context),
- if (listShown && widget.onOpenSettings != null)
+ // A wide window's rail offers Settings; the gear stays on a phone.
+ if (listShown &&
+ !ShellRailScope.isShown(context) &&
+ widget.onOpenSettings != null)
_settingsButton(context),
],
child: body,
diff --git a/app/lib/features/runs/ui/run_detail_tab_bodies.dart b/app/lib/features/runs/ui/run_detail_tab_bodies.dart
index 134ba8a1..a6377a0a 100644
--- a/app/lib/features/runs/ui/run_detail_tab_bodies.dart
+++ b/app/lib/features/runs/ui/run_detail_tab_bodies.dart
@@ -107,7 +107,12 @@ Widget runDetailSummaryTab({
title: 'Output',
controller: outputController,
copyText: runFieldCopyText(run['output']),
- body: RunFieldBody(value: run['output'], empty: visitEmptyOutput),
+ // Output starts open, so it is a sliver: a long one builds only the
+ // fields on screen.
+ sliverBody: RunFieldSliver(
+ value: run['output'],
+ empty: visitEmptyOutput,
+ ),
),
const SliverToBoxAdapter(child: SizedBox(height: 16)),
const SliverFloatingBarClearance(),
@@ -115,19 +120,25 @@ Widget runDetailSummaryTab({
);
}
-/// A summary section that starts closed, follows its [controller] (so a
-/// search hit can open it), and offers a copy of its recorded text.
+/// A summary section that follows its [controller] (its open state starts from
+/// the controller's; a search hit can open it), and offers a copy of its
+/// recorded text.
class _StickyField extends StatefulWidget {
const _StickyField({
super.key,
required this.title,
- required this.body,
+ this.body,
+ this.sliverBody,
this.controller,
this.copyText,
- });
+ }) : assert((body == null) != (sliverBody == null));
final String title;
- final Widget body;
+
+ /// The content as a box, or as [sliverBody] for a long one (see
+ /// [StickySection.sliverBody]); exactly one is given.
+ final Widget? body;
+ final Widget? sliverBody;
final ExpansibleController? controller;
final String? copyText;
@@ -158,25 +169,31 @@ class _StickyFieldState extends State<_StickyField> {
final copyText = widget.copyText;
return ListenableBuilder(
listenable: _controller,
- builder: (context, _) => StickySection(
- title: widget.title,
- open: _controller.isExpanded,
- onToggle: () => _controller.isExpanded
- ? _controller.collapse()
- : _controller.expand(),
- trailing: [
- if (copyText != null && copyText.isNotEmpty)
- IconButton(
- tooltip: 'Copy ${widget.title}',
- onPressed: _copy,
- icon: Icon(_copied ? Icons.check : Icons.copy),
- ),
- ],
- body: Padding(
- padding: const EdgeInsets.fromLTRB(16, 0, 16, 16),
- child: widget.body,
- ),
- ),
+ builder: (context, _) {
+ // The body's own padding, the same for the box and the sliver form.
+ const padding = EdgeInsets.fromLTRB(16, 0, 16, 16);
+ final box = widget.body;
+ final sliver = widget.sliverBody;
+ return StickySection(
+ title: widget.title,
+ open: _controller.isExpanded,
+ onToggle: () => _controller.isExpanded
+ ? _controller.collapse()
+ : _controller.expand(),
+ trailing: [
+ if (copyText != null && copyText.isNotEmpty)
+ IconButton(
+ tooltip: 'Copy ${widget.title}',
+ onPressed: _copy,
+ icon: Icon(_copied ? Icons.check : Icons.copy),
+ ),
+ ],
+ body: box == null ? null : Padding(padding: padding, child: box),
+ sliverBody: sliver == null
+ ? null
+ : SliverPadding(padding: padding, sliver: sliver),
+ );
+ },
);
}
}
diff --git a/app/lib/features/runs/ui/run_detail_tabs.dart b/app/lib/features/runs/ui/run_detail_tabs.dart
index d303ba93..940078a6 100644
--- a/app/lib/features/runs/ui/run_detail_tabs.dart
+++ b/app/lib/features/runs/ui/run_detail_tabs.dart
@@ -98,12 +98,13 @@ class _RunDetailTabsState extends State {
Route? _visitRoute;
late final ValueNotifier _liveRun = ValueNotifier(widget.run);
- /// The Summary's collapsible Input and Output sections. A search text hit
- /// expands the one its recorded field names, exactly as the browser opens the
- /// matching Summary section. The detail owns them so the tab body stays a
- /// presentation widget.
+ /// The Summary's collapsible Input and Output sections. Output starts open
+ /// and Input starts closed; the operator may close either for this view. A
+ /// search text hit expands the one its recorded field names, exactly as the
+ /// browser opens the matching Summary section. The detail owns them so the
+ /// tab body stays a presentation widget.
final _inputSection = ExpansibleController();
- final _outputSection = ExpansibleController();
+ final _outputSection = ExpansibleController()..expand();
/// The search request last applied by this detail, so a rebuild of the same
/// request never reopens a pane the operator closed in the meantime.
@@ -124,6 +125,12 @@ class _RunDetailTabsState extends State {
_applySearchSelection();
}
+ /// The Summary's default sections: Input closed, Output open.
+ void _resetSummarySections() {
+ _inputSection.collapse();
+ _outputSection.expand();
+ }
+
@override
void dispose() {
_inputSection.dispose();
@@ -146,8 +153,7 @@ class _RunDetailTabsState extends State {
_tab = RunDetailTab.summary;
_selectedStage = null;
_selectedVisit = null;
- _inputSection.collapse();
- _outputSection.collapse();
+ _resetSummarySections();
_applyInitialVisit();
} else if (!sameTarget) {
// A route that names another stage or visit is applied to the same run.
@@ -231,10 +237,10 @@ class _RunDetailTabsState extends State {
case RunSummarySection.output:
_outputSection.expand();
case null:
- // A hit that names no section must not leave a previously expanded
- // one open; the Summary panel starts collapsed.
- _inputSection.collapse();
- _outputSection.collapse();
+ // A hit that names no section must not leave a previously toggled
+ // one in a state the operator did not open; the Summary returns to
+ // its default sections.
+ _resetSummarySections();
}
case RunVisitTarget(:final stageKey, :final timelineIndex):
if (detailVisitStepAt(widget.run, timelineIndex) == null) return;
diff --git a/app/lib/features/runs/ui/run_detail_visit_sections.dart b/app/lib/features/runs/ui/run_detail_visit_sections.dart
index df811ae2..27b364fd 100644
--- a/app/lib/features/runs/ui/run_detail_visit_sections.dart
+++ b/app/lib/features/runs/ui/run_detail_visit_sections.dart
@@ -111,7 +111,8 @@ Widget runVisitSectionBody({
);
switch (section) {
case RunVisitSection.summary:
- // Input then Output, each a sticky collapsible with a copy button.
+ // Input then Output, each a sticky collapsible with a copy button; Output
+ // starts open.
return _VisitSummary(
key: ValueKey('run-visit-summary-$visitIndex'),
input: step['input'],
@@ -181,7 +182,9 @@ class _VisitSummary extends StatefulWidget {
}
class _VisitSummaryState extends State<_VisitSummary> {
- final Set _closed = {'Input', 'Output'};
+ /// The sections the operator has closed. Input starts closed; Output starts
+ /// open, and this set is per visit view.
+ final Set _closed = {'Input'};
String? _copied;
Future _copy(String name, dynamic value) async {
@@ -189,7 +192,14 @@ class _VisitSummaryState extends State<_VisitSummary> {
if (mounted) setState(() => _copied = name);
}
- Widget _section(String name, dynamic value, String empty) {
+ /// [lazy] builds the field as a sliver, for a section open by default (the
+ /// Output): a long one then lays out only the fields on screen.
+ Widget _section(
+ String name,
+ dynamic value,
+ String empty, {
+ bool lazy = false,
+ }) {
final copy = IconButton(
key: ValueKey('run-visit-copy-$name'),
tooltip: 'Copy $name',
@@ -197,6 +207,7 @@ class _VisitSummaryState extends State<_VisitSummary> {
icon: Icon(_copied == name ? Icons.check : Icons.copy),
);
final open = !_closed.contains(name);
+ const padding = EdgeInsets.fromLTRB(16, 0, 16, 16);
return StickySection(
key: ValueKey('run-visit-section-$name'),
title: name,
@@ -205,10 +216,18 @@ class _VisitSummaryState extends State<_VisitSummary> {
if (!_closed.remove(name)) _closed.add(name);
}),
trailing: [copy],
- body: Padding(
- padding: const EdgeInsets.fromLTRB(16, 0, 16, 16),
- child: RunFieldBody(value: value, empty: empty),
- ),
+ body: lazy
+ ? null
+ : Padding(
+ padding: padding,
+ child: RunFieldBody(value: value, empty: empty),
+ ),
+ sliverBody: lazy
+ ? SliverPadding(
+ padding: padding,
+ sliver: RunFieldSliver(value: value, empty: empty),
+ )
+ : null,
);
}
@@ -221,7 +240,7 @@ class _VisitSummaryState extends State<_VisitSummary> {
const SliverTopBarClearance(),
if (widget.facts case final facts?) SliverToBoxAdapter(child: facts),
_section('Input', widget.input, visitEmptyInput),
- _section('Output', widget.output, visitEmptyOutput),
+ _section('Output', widget.output, visitEmptyOutput, lazy: true),
const SliverFloatingBarClearance(),
],
);
diff --git a/app/lib/features/runs/ui/run_field_body.dart b/app/lib/features/runs/ui/run_field_body.dart
index d1ce93ad..355539b0 100644
--- a/app/lib/features/runs/ui/run_field_body.dart
+++ b/app/lib/features/runs/ui/run_field_body.dart
@@ -55,40 +55,99 @@ class RunFieldBody extends StatelessWidget {
@override
Widget build(BuildContext context) {
- final map = value is Map ? Map.from(value as Map) : null;
- if (map == null || map.isEmpty) return _plain(empty);
- if (map.length == 1 && map.keys.single.toLowerCase() == 'markdown') {
- return _value(runFieldText(map.values.single));
+ final map = _runFieldMap(value);
+ if (map == null || map.isEmpty) {
+ return _runFieldPlain(empty, textBuilder);
+ }
+ if (_isMarkdownDocument(map)) {
+ return _runFieldValue(runFieldText(map.values.single), textBuilder);
}
- final caption = Theme.of(context).textTheme.labelMedium?.copyWith(
- fontWeight: FontWeight.w600,
- color: Theme.of(context).colorScheme.onSurfaceVariant,
- );
return Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
for (final (index, entry) in map.entries.indexed)
- Padding(
- padding: EdgeInsets.only(top: index == 0 ? 0 : 12),
- child: Column(
- crossAxisAlignment: CrossAxisAlignment.start,
- children: [
- Text(
- entry.key.trim().isEmpty ? 'value' : entry.key,
- style: caption,
- ),
- const SizedBox(height: 2),
- _value(runFieldText(entry.value)),
- ],
- ),
- ),
+ _runFieldRow(context, index, entry, textBuilder),
],
);
}
-
- Widget _value(String text) => runFieldLooksLikeMarkdown(text)
- ? ChatMarkdownView(text: text)
- : _plain(text);
-
- Widget _plain(String text) => textBuilder?.call(text) ?? SelectableText(text);
}
+
+/// [RunFieldBody] as a sliver, for a section of a [CustomScrollView] that is
+/// open by default. A field map builds and lays out only the fields on screen,
+/// however many there are, so a long Output does not cost a full layout when
+/// its section opens. Its rows take the full width the sliver gives them; the
+/// host pads it.
+class RunFieldSliver extends StatelessWidget {
+ const RunFieldSliver({
+ super.key,
+ required this.value,
+ required this.empty,
+ this.textBuilder,
+ });
+
+ final dynamic value;
+ final String empty;
+
+ /// Draws a plain value; the host's selectable text by default.
+ final Widget Function(String text)? textBuilder;
+
+ @override
+ Widget build(BuildContext context) {
+ final map = _runFieldMap(value);
+ if (map == null || map.isEmpty || _isMarkdownDocument(map)) {
+ return SliverToBoxAdapter(
+ child: RunFieldBody(
+ value: value,
+ empty: empty,
+ textBuilder: textBuilder,
+ ),
+ );
+ }
+ final entries = map.entries.toList(growable: false);
+ return SliverList.builder(
+ itemCount: entries.length,
+ itemBuilder: (context, index) =>
+ _runFieldRow(context, index, entries[index], textBuilder),
+ );
+ }
+}
+
+Map? _runFieldMap(dynamic value) =>
+ value is Map ? Map.from(value) : null;
+
+/// A lone `markdown` field, shown as the document itself.
+bool _isMarkdownDocument(Map map) =>
+ map.length == 1 && map.keys.single.toLowerCase() == 'markdown';
+
+/// One recorded field: its name, then its value.
+Widget _runFieldRow(
+ BuildContext context,
+ int index,
+ MapEntry entry,
+ Widget Function(String text)? textBuilder,
+) {
+ final theme = Theme.of(context);
+ final caption = theme.textTheme.labelMedium?.copyWith(
+ fontWeight: FontWeight.w600,
+ color: theme.colorScheme.onSurfaceVariant,
+ );
+ return Padding(
+ padding: EdgeInsets.only(top: index == 0 ? 0 : 12),
+ child: Column(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Text(entry.key.trim().isEmpty ? 'value' : entry.key, style: caption),
+ const SizedBox(height: 2),
+ _runFieldValue(runFieldText(entry.value), textBuilder),
+ ],
+ ),
+ );
+}
+
+Widget _runFieldValue(String text, Widget Function(String text)? textBuilder) =>
+ runFieldLooksLikeMarkdown(text)
+ ? ChatMarkdownView(text: text)
+ : _runFieldPlain(text, textBuilder);
+
+Widget _runFieldPlain(String text, Widget Function(String text)? textBuilder) =>
+ textBuilder?.call(text) ?? SelectableText(text);
diff --git a/app/lib/features/settings/keyboard_shortcuts_registry.dart b/app/lib/features/settings/keyboard_shortcuts_registry.dart
index 22f12a9d..85f3d2f0 100644
--- a/app/lib/features/settings/keyboard_shortcuts_registry.dart
+++ b/app/lib/features/settings/keyboard_shortcuts_registry.dart
@@ -5,6 +5,7 @@ import '../chat/workspace/chat_float_shortcut.dart';
import '../terminal/terminal_shortcuts.dart';
import '../../shell/windows/window_shortcuts.dart';
import '../../shell/shell_chat_shortcut.dart';
+import '../../shell/shell_runs_pipelines_shortcut.dart';
import '../../shell/shell_search_shortcut_labels.dart';
/// A shortcut entry shown in the in-app help. Keeping these entries together
@@ -61,6 +62,12 @@ class KeyboardShortcutRegistry {
? 'Shows the open chat and focuses its message input. The browser may reserve Ctrl+K.'
: 'Shows the open chat and focuses its message input. In the terminal Ctrl+K stays kill-line; Alt+K still opens Chat.',
),
+ const KeyboardShortcutEntry(
+ action: 'Switch between Runs and Pipelines',
+ keys: shellRunsPipelinesShortcutLabel,
+ caveat:
+ 'Goes to Runs from other destinations and to Pipelines from Runs. In a text field or the terminal Ctrl+A keeps its own meaning.',
+ ),
KeyboardShortcutEntry(
action: 'Toggle Center Stage',
keys:
diff --git a/app/lib/features/settings/settings_device_delivery_section.dart b/app/lib/features/settings/settings_device_delivery_section.dart
index f5511c17..494b4ecb 100644
--- a/app/lib/features/settings/settings_device_delivery_section.dart
+++ b/app/lib/features/settings/settings_device_delivery_section.dart
@@ -16,11 +16,24 @@ const deviceDeliveryNote =
'quiet "Pipelines is connected" notification while it runs.';
const deviceDeliveryBatteryLabel = 'Allow background delivery';
const deviceDeliveryNotificationsLabel = 'Allow notifications';
+const deviceDeliveryWarningTitle = 'Delivery can pause while idle';
+const deviceDeliveryWarningText =
+ 'Android may pause Pipelines in the background, so notifications can '
+ 'arrive late. Allow background delivery above.';
+const deviceDeliverySamsungNote =
+ 'Samsung phones: also add Pipelines under Settings › Battery › '
+ 'Background usage limits › Never sleeping apps.';
+const deviceDeliveryLogTitle = 'Connection log';
+const deviceDeliveryLogEmpty = 'No connection events yet';
abstract final class DeviceDeliveryKeys {
static const toggle = ValueKey('settings.deviceDelivery.toggle');
static const status = ValueKey('settings.deviceDelivery.status');
static const battery = ValueKey('settings.deviceDelivery.battery');
+ static const batteryWarning = ValueKey(
+ 'settings.deviceDelivery.batteryWarning',
+ );
+ static const log = ValueKey('settings.deviceDelivery.log');
static const permission = ValueKey(
'settings.deviceDelivery.permission',
);
@@ -66,7 +79,7 @@ class _SettingsDeviceDeliverySectionState
void initState() {
super.initState();
_lifecycle;
- unawaited(_controller.load());
+ unawaited(_controller.open());
}
@override
@@ -136,7 +149,45 @@ class _SettingsDeviceDeliverySectionState
enabled: !status.batteryExempt && !_controller.busy,
onTap: () => unawaited(_controller.allowBackgroundDelivery()),
),
+ if (status != null && enabled && !status.batteryExempt)
+ SettingsRow(
+ key: DeviceDeliveryKeys.batteryWarning,
+ leading: Icon(
+ Icons.warning_amber_rounded,
+ color: settingsErrorColor(context),
+ ),
+ title: const Text(deviceDeliveryWarningTitle),
+ subtitle: Text(
+ '$deviceDeliveryWarningText\n$deviceDeliverySamsungNote',
+ ),
+ ),
+ if (status != null)
+ ExpansionTile(
+ key: DeviceDeliveryKeys.log,
+ title: const Text(deviceDeliveryLogTitle),
+ children: _logRows(),
+ ),
],
);
}
+
+ List _logRows() {
+ final events = _controller.events;
+ if (events.isEmpty) {
+ return const [ListTile(title: Text(deviceDeliveryLogEmpty))];
+ }
+ return [
+ for (final event in events)
+ ListTile(
+ dense: true,
+ title: Text(event.title),
+ subtitle: Text(
+ [
+ event.timeLabel,
+ if (event.detail != null) event.detail!,
+ ].join('\n'),
+ ),
+ ),
+ ];
+ }
}
diff --git a/app/lib/features/settings/settings_keys.dart b/app/lib/features/settings/settings_keys.dart
index 337757ff..6c4e868b 100644
--- a/app/lib/features/settings/settings_keys.dart
+++ b/app/lib/features/settings/settings_keys.dart
@@ -13,4 +13,5 @@ abstract final class SettingsKeys {
static const keyboardShortcuts = ValueKey(
'settings.keyboardShortcuts',
);
+ static const walkthrough = ValueKey('settings.walkthrough');
}
diff --git a/app/lib/features/settings/settings_screen.dart b/app/lib/features/settings/settings_screen.dart
index 1e63875d..ce8f097b 100644
--- a/app/lib/features/settings/settings_screen.dart
+++ b/app/lib/features/settings/settings_screen.dart
@@ -37,6 +37,7 @@ import 'server_connections.dart';
import 'saved_servers_section.dart';
import 'managed_connection_section.dart';
import 'settings_keyboard_shortcuts_section.dart';
+import 'settings_walkthrough_section.dart';
part 'settings_topic_pages.dart';
diff --git a/app/lib/features/settings/settings_topic_pages.dart b/app/lib/features/settings/settings_topic_pages.dart
index 8d89bd49..7dee4895 100644
--- a/app/lib/features/settings/settings_topic_pages.dart
+++ b/app/lib/features/settings/settings_topic_pages.dart
@@ -85,7 +85,10 @@ extension _SettingsTopicPages on _SettingsScreenState {
SettingsGroup(
title: 'Help',
leadingRows: true,
- children: const [SettingsKeyboardShortcutsSection()],
+ children: const [
+ SettingsKeyboardShortcutsSection(),
+ SettingsWalkthroughSection(),
+ ],
),
if (widget.onOpenSchedules case final open?)
SettingsGroup(
diff --git a/app/lib/features/settings/settings_walkthrough_section.dart b/app/lib/features/settings/settings_walkthrough_section.dart
new file mode 100644
index 00000000..5d31e398
--- /dev/null
+++ b/app/lib/features/settings/settings_walkthrough_section.dart
@@ -0,0 +1,23 @@
+import 'package:flutter/material.dart';
+
+import '../walkthrough/first_run_walkthrough.dart';
+import 'settings_keys.dart';
+import 'settings_row.dart';
+
+/// Reopens the first-run walkthrough. It only shows the walkthrough; it never
+/// changes the device's seen record.
+class SettingsWalkthroughSection extends StatelessWidget {
+ const SettingsWalkthroughSection({super.key});
+
+ @override
+ Widget build(BuildContext context) => SettingsRow(
+ key: SettingsKeys.walkthrough,
+ leading: const Icon(Icons.school_outlined),
+ title: const Text('Show the walkthrough'),
+ subtitle: const Text(
+ 'Four short steps: connect, set up an agent, run, chat.',
+ ),
+ chevron: true,
+ onTap: () => showFirstRunWalkthrough(context),
+ );
+}
diff --git a/app/lib/features/terminal/terminal_open_action.dart b/app/lib/features/terminal/terminal_open_action.dart
index f52f241b..7bf02fb3 100644
--- a/app/lib/features/terminal/terminal_open_action.dart
+++ b/app/lib/features/terminal/terminal_open_action.dart
@@ -3,9 +3,12 @@ import 'dart:async';
import 'package:flutter/material.dart';
import '../../core/api_gateway.dart';
+import '../../shell/list_detail_policy.dart';
import '../../ui/adaptive/segmented_bar_overflow.dart';
+import '../chat/ui/sessions/chat_adaptive.dart';
import 'terminal_hub.dart';
import 'terminal_scope.dart';
+import 'terminal_toggle_button.dart';
/// The first time the terminal is shown in an app run it starts one
/// terminal, as New terminal does (it shows the machine's login prompt),
@@ -49,6 +52,23 @@ void openInTerminal(
);
}
+/// The open chat's own bar button that shows or hides the terminal, on a
+/// narrow layout. It is a plain [ChatBarAction] like Files and More, so it
+/// matches them in style, size and states. A wide layout returns null: its
+/// shell bar keeps the terminal button over the list column. Null too with
+/// no terminal surface.
+Widget? terminalChatBarAction(BuildContext context) {
+ if (showsListBesideDetail(context)) return null;
+ final actions = TerminalScope.maybeOf(context);
+ if (actions == null) return null;
+ return ChatBarAction(
+ label: TerminalToggleButton.label,
+ identifier: 'chat-terminal-toggle',
+ onPressed: actions.toggle,
+ materialIcon: Icons.terminal,
+ );
+}
+
/// The chat actions menu's "Open in terminal" for the chat's folder, or
/// null when the app has no terminal surface or the chat no folder.
Widget? terminalOpenMenuAction(
diff --git a/app/lib/features/terminal/terminal_toggle_button.dart b/app/lib/features/terminal/terminal_toggle_button.dart
index 104fd351..b92a38ed 100644
--- a/app/lib/features/terminal/terminal_toggle_button.dart
+++ b/app/lib/features/terminal/terminal_toggle_button.dart
@@ -6,6 +6,9 @@ import 'terminal_shortcuts.dart';
/// The shell bar's Terminal button: shows or hides the terminal (also
/// Alt+T, Ctrl+T, Cmd+T and Ctrl+`, where the platform delivers them).
+///
+/// It is a plain bar IconButton like Files and More: no selected tint, so
+/// its shown state is announced to assistive technology only.
class TerminalToggleButton extends StatelessWidget {
const TerminalToggleButton({super.key, required this.layout});
@@ -22,12 +25,14 @@ class TerminalToggleButton extends StatelessWidget {
listenable: layout,
builder: (context, _) {
final shown = layout.visible;
- return IconButton(
- key: const ValueKey('shell.terminal'),
- tooltip: label,
- isSelected: shown,
- onPressed: actions.toggle,
- icon: const Icon(Icons.terminal),
+ return Semantics(
+ toggled: shown,
+ child: IconButton(
+ key: const ValueKey('shell.terminal'),
+ tooltip: label,
+ onPressed: actions.toggle,
+ icon: const Icon(Icons.terminal),
+ ),
);
},
);
diff --git a/app/lib/features/terminal/terminal_window.dart b/app/lib/features/terminal/terminal_window.dart
index 1f47033f..de4a5f81 100644
--- a/app/lib/features/terminal/terminal_window.dart
+++ b/app/lib/features/terminal/terminal_window.dart
@@ -17,7 +17,7 @@ const _terminalContent = 'terminal';
///
/// [TerminalLayout] stays the terminal's own state (shown, panel or float):
/// showing it in float mode opens or shows the window, hiding minimises it,
-/// and the window's Minimise and Close hide the terminal.
+/// and the window's X (minimise) hides the terminal.
class TerminalWindows {
TerminalWindows({
required this.manager,
@@ -110,7 +110,7 @@ class TerminalWindows {
if (legacy && layout.maximized) manager.setMaximized(entry.id, true);
}
- /// The window's Minimise or Close (or the windows' own show and hide)
+ /// The window's X or Minimise (or the windows' own show and hide)
/// hides the terminal.
void _windowsChanged() {
if (!_started || !_ready || _syncing || !_wanted) return;
diff --git a/app/lib/features/walkthrough/first_run_walkthrough.dart b/app/lib/features/walkthrough/first_run_walkthrough.dart
new file mode 100644
index 00000000..bedcbcac
--- /dev/null
+++ b/app/lib/features/walkthrough/first_run_walkthrough.dart
@@ -0,0 +1,183 @@
+import 'package:flutter/material.dart';
+
+import '../../ui/adaptive/app_popups.dart';
+import 'walkthrough_harness_command.dart';
+import 'walkthrough_steps.dart';
+
+/// Opens the walkthrough as a Material details sheet on phones and a dialog on
+/// wide windows. [onClosed] runs once however it closes (Skip, Done, the close
+/// button or a tap outside), so the caller can record it as seen.
+Future showFirstRunWalkthrough(
+ BuildContext context, {
+ Future Function()? onClosed,
+}) async {
+ await showAppDetails(
+ context,
+ maxWidth: 560,
+ builder: (sheet) =>
+ FirstRunWalkthrough(onClose: () => Navigator.of(sheet).pop()),
+ );
+ await onClosed?.call();
+}
+
+/// The four-page stepper: Back and Next between pages, Skip on every page and
+/// Done on the last. Every control is a standard Material button; the layout
+/// wraps rather than clipping at large text scales.
+class FirstRunWalkthrough extends StatefulWidget {
+ const FirstRunWalkthrough({
+ super.key,
+ required this.onClose,
+ this.steps = walkthroughSteps,
+ });
+
+ /// Called by Skip, Done and the close button.
+ final VoidCallback onClose;
+ final List steps;
+
+ @override
+ State createState() => _FirstRunWalkthroughState();
+}
+
+class _FirstRunWalkthroughState extends State {
+ int _index = 0;
+
+ bool get _last => _index == widget.steps.length - 1;
+
+ void _back() => setState(() => _index = _index > 0 ? _index - 1 : 0);
+
+ void _next() => setState(() => _index = _last ? _index : _index + 1);
+
+ @override
+ Widget build(BuildContext context) {
+ final step = widget.steps[_index];
+ final theme = Theme.of(context);
+ final content = Semantics(
+ scopesRoute: true,
+ namesRoute: true,
+ explicitChildNodes: true,
+ label: 'Pipelines walkthrough',
+ child: Padding(
+ padding: const EdgeInsets.fromLTRB(24, 8, 24, 24),
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ Text(
+ 'Step ${_index + 1} of ${widget.steps.length}',
+ key: const ValueKey('walkthrough.progress'),
+ style: theme.textTheme.labelLarge,
+ ),
+ const SizedBox(height: 8),
+ LinearProgressIndicator(value: (_index + 1) / widget.steps.length),
+ const SizedBox(height: 20),
+ Row(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ Icon(step.icon, color: theme.colorScheme.primary),
+ const SizedBox(width: 12),
+ Expanded(
+ child: Text(
+ step.title,
+ key: ValueKey('walkthrough.title.$_index'),
+ style: theme.textTheme.headlineSmall,
+ ),
+ ),
+ ],
+ ),
+ const SizedBox(height: 12),
+ Text(step.body, style: theme.textTheme.bodyLarge),
+ for (final point in step.points) ...[
+ const SizedBox(height: 8),
+ _Point(text: point),
+ ],
+ if (step.showsHarnessCommand) ...[
+ const SizedBox(height: 16),
+ const WalkthroughHarnessCommand(),
+ ],
+ const SizedBox(height: 24),
+ _Footer(
+ last: _last,
+ canGoBack: _index > 0,
+ onBack: _back,
+ onNext: _last ? widget.onClose : _next,
+ onSkip: widget.onClose,
+ ),
+ ],
+ ),
+ ),
+ );
+ // A wide window wraps the sheet's content in its own scroll view; a phone
+ // sheet does not, so the page scrolls here at large text scales.
+ return usesDesktopPopups(context)
+ ? content
+ : SingleChildScrollView(child: content);
+ }
+}
+
+class _Point extends StatelessWidget {
+ const _Point({required this.text});
+
+ final String text;
+
+ @override
+ Widget build(BuildContext context) => Row(
+ crossAxisAlignment: CrossAxisAlignment.start,
+ children: [
+ const Padding(
+ padding: EdgeInsets.only(top: 2),
+ child: Icon(Icons.circle, size: 6),
+ ),
+ const SizedBox(width: 12),
+ Expanded(
+ child: Text(text, style: Theme.of(context).textTheme.bodyMedium),
+ ),
+ ],
+ );
+}
+
+class _Footer extends StatelessWidget {
+ const _Footer({
+ required this.last,
+ required this.canGoBack,
+ required this.onBack,
+ required this.onNext,
+ required this.onSkip,
+ });
+
+ final bool last;
+ final bool canGoBack;
+ final VoidCallback onBack;
+ final VoidCallback onNext;
+ final VoidCallback onSkip;
+
+ @override
+ Widget build(BuildContext context) => Wrap(
+ alignment: WrapAlignment.spaceBetween,
+ crossAxisAlignment: WrapCrossAlignment.center,
+ spacing: 8,
+ runSpacing: 8,
+ children: [
+ TextButton(
+ key: const ValueKey('walkthrough.skip'),
+ onPressed: onSkip,
+ child: const Text('Skip'),
+ ),
+ Wrap(
+ spacing: 8,
+ runSpacing: 8,
+ children: [
+ TextButton(
+ key: const ValueKey('walkthrough.back'),
+ onPressed: canGoBack ? onBack : null,
+ child: const Text('Back'),
+ ),
+ FilledButton(
+ key: const ValueKey('walkthrough.next'),
+ onPressed: onNext,
+ child: Text(last ? 'Done' : 'Next'),
+ ),
+ ],
+ ),
+ ],
+ );
+}
diff --git a/app/lib/features/walkthrough/walkthrough_gate.dart b/app/lib/features/walkthrough/walkthrough_gate.dart
new file mode 100644
index 00000000..a560ece8
--- /dev/null
+++ b/app/lib/features/walkthrough/walkthrough_gate.dart
@@ -0,0 +1,200 @@
+import 'dart:async';
+
+import 'package:flutter/widgets.dart';
+
+import '../../core/api_gateway.dart';
+import 'first_run_walkthrough.dart';
+import 'walkthrough_store.dart';
+
+/// Reports whether the server has no pipelines, runs or chats yet. Returns null
+/// when any of the three lists cannot be read, so an unreadable server never
+/// triggers the walkthrough.
+Future serverHasNoWorkYet(ApiGateway? gateway) async {
+ if (gateway == null) return null;
+ try {
+ final replies = await Future.wait(>[
+ gateway.call('list_pipelines', {'include_archived': true}),
+ gateway.call('list_runs'),
+ gateway.call('chat_sessions'),
+ ]);
+ final lists = [
+ replies[0]['pipelines'],
+ replies[1]['runs'],
+ replies[2]['chat_sessions'],
+ ];
+ if (lists.any((list) => list is! List)) return null;
+ return lists.every((list) => (list as List).isEmpty);
+ } catch (_) {
+ return null;
+ }
+}
+
+/// Offers the walkthrough from the Pipelines page, which is the first screen a
+/// new user sees. It is offered when:
+///
+/// * the device has not finished or skipped it yet (first launch, once); or
+/// * the device already has, and the connected server has no pipelines, runs
+/// or chats, and that server has not been offered it before.
+///
+/// The server check needs a connected session. While disconnected it waits, and
+/// it runs again on each new connection until the server answers. A check that
+/// cannot read the server leaves the gate open to retry; a decided check (the
+/// walkthrough shown, or the server has work) ends it for this mount.
+///
+/// Nothing is shown while the store cannot be read, because an unavailable
+/// store reports "seen". The check runs only while [enabled] (the Pipelines tab
+/// is the one showing).
+class FirstRunWalkthroughGate extends StatefulWidget {
+ const FirstRunWalkthroughGate({
+ super.key,
+ required this.child,
+ required this.store,
+ required this.enabled,
+ required this.serverScope,
+ required this.connection,
+ required this.connected,
+ this.gateway,
+ });
+
+ final Widget child;
+ final WalkthroughStore store;
+
+ /// Whether the Pipelines page is the one showing.
+ final bool enabled;
+
+ /// The connected server's scope, recorded when the walkthrough is offered.
+ final String serverScope;
+
+ /// Notifies when the connection may have changed; the gate re-reads
+ /// [connected] on each notification.
+ final Listenable connection;
+
+ /// Whether the server session is connected right now.
+ final bool Function() connected;
+
+ /// The connected server's gateway, used for the empty-server check.
+ final ApiGateway? gateway;
+
+ @override
+ State createState() =>
+ _FirstRunWalkthroughGateState();
+}
+
+class _FirstRunWalkthroughGateState extends State {
+ /// The offer is decided for this mount: shown, or nothing left to offer.
+ bool _decided = false;
+
+ /// An offer is in flight.
+ bool _running = false;
+
+ /// A new connection arrived while an offer was in flight.
+ bool _connectedAgain = false;
+ late bool _wasConnected;
+
+ @override
+ void initState() {
+ super.initState();
+ _wasConnected = widget.connected();
+ widget.connection.addListener(_onConnectionChanged);
+ _scheduleIfEnabled();
+ }
+
+ @override
+ void didUpdateWidget(FirstRunWalkthroughGate oldWidget) {
+ super.didUpdateWidget(oldWidget);
+ if (oldWidget.connection != widget.connection) {
+ oldWidget.connection.removeListener(_onConnectionChanged);
+ widget.connection.addListener(_onConnectionChanged);
+ }
+ _scheduleIfEnabled();
+ }
+
+ @override
+ void dispose() {
+ widget.connection.removeListener(_onConnectionChanged);
+ super.dispose();
+ }
+
+ /// Acts only on a disconnected-to-connected transition, so frequent session
+ /// notifications while connected never repeat the server check.
+ void _onConnectionChanged() {
+ final connected = widget.connected();
+ final became = connected && !_wasConnected;
+ _wasConnected = connected;
+ if (!became || _decided) return;
+ if (_running) {
+ _connectedAgain = true;
+ return;
+ }
+ _scheduleIfEnabled();
+ }
+
+ void _scheduleIfEnabled() {
+ if (_decided || _running || !widget.enabled) return;
+ _running = true;
+ // A connection can arrive between frames; the post-frame callback needs a
+ // frame, so request one explicitly.
+ WidgetsBinding.instance.addPostFrameCallback((_) {
+ if (!_active) {
+ // Pipelines is hidden (or the gate is gone): release the flag so a
+ // later enable reschedules the offer through didUpdateWidget.
+ _running = false;
+ return;
+ }
+ unawaited(_runOffer());
+ });
+ WidgetsBinding.instance.ensureVisualUpdate();
+ }
+
+ /// The gate may offer only while mounted and while the Pipelines page is the
+ /// one showing. Checked after every await and before every show.
+ bool get _active => mounted && widget.enabled;
+
+ Future _runOffer() async {
+ try {
+ await _offer();
+ } finally {
+ _running = false;
+ final again = _connectedAgain;
+ _connectedAgain = false;
+ if (again && !_decided) _scheduleIfEnabled();
+ }
+ }
+
+ Future _offer() async {
+ final seen = await widget.store.isSeen();
+ if (!_active) return;
+ if (!seen) {
+ _decided = true;
+ await _showIfActive();
+ return;
+ }
+ if (await widget.store.wasOffered(widget.serverScope)) {
+ if (!_active) return;
+ _decided = true;
+ return;
+ }
+ // Wait for a connection; the connection listener runs the check again.
+ if (!widget.connected()) return;
+ final empty = await serverHasNoWorkYet(widget.gateway);
+ if (!_active) return;
+ // Unreadable: stay open so the next connection retries the check.
+ if (empty == null) return;
+ _decided = true;
+ if (!empty) return;
+ await widget.store.markOffered(widget.serverScope);
+ await _showIfActive();
+ }
+
+ Future _showIfActive() async {
+ if (!_active) return;
+ await _show();
+ }
+
+ Future _show() async {
+ await showFirstRunWalkthrough(context, onClosed: widget.store.markSeen);
+ }
+
+ @override
+ Widget build(BuildContext context) => widget.child;
+}
diff --git a/app/lib/features/walkthrough/walkthrough_harness_command.dart b/app/lib/features/walkthrough/walkthrough_harness_command.dart
new file mode 100644
index 00000000..7e560449
--- /dev/null
+++ b/app/lib/features/walkthrough/walkthrough_harness_command.dart
@@ -0,0 +1,86 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+
+import 'walkthrough_steps.dart';
+
+/// The harness page's command: an agent picker and the one command it selects,
+/// with a single copy button for that command.
+class WalkthroughHarnessCommand extends StatefulWidget {
+ const WalkthroughHarnessCommand({super.key});
+
+ @override
+ State createState() =>
+ _WalkthroughHarnessCommandState();
+}
+
+class _WalkthroughHarnessCommandState extends State {
+ String _agent = harnessAgents.first;
+ bool _copied = false;
+
+ Future _copy(String command) async {
+ try {
+ await Clipboard.setData(ClipboardData(text: command));
+ } catch (_) {
+ // The command stays selectable, so a failed copy never claims success.
+ return;
+ }
+ if (!mounted) return;
+ setState(() => _copied = true);
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ final scheme = Theme.of(context).colorScheme;
+ final command = harnessSetupCommand(_agent);
+ return Column(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ Text('Agent', style: Theme.of(context).textTheme.labelLarge),
+ const SizedBox(height: 8),
+ Wrap(
+ spacing: 8,
+ runSpacing: 8,
+ children: [
+ for (final agent in harnessAgents)
+ ChoiceChip(
+ key: ValueKey('walkthrough.agent.$agent'),
+ label: Text(agent),
+ selected: agent == _agent,
+ onSelected: (_) => setState(() {
+ _agent = agent;
+ _copied = false;
+ }),
+ ),
+ ],
+ ),
+ const SizedBox(height: 12),
+ DecoratedBox(
+ decoration: BoxDecoration(
+ color: scheme.surfaceContainerHighest,
+ borderRadius: BorderRadius.circular(12),
+ ),
+ child: Padding(
+ padding: const EdgeInsets.only(left: 12, right: 4),
+ child: Row(
+ children: [
+ Expanded(
+ child: SelectableText(
+ command,
+ key: const ValueKey('walkthrough.command'),
+ style: Theme.of(context).textTheme.bodyLarge,
+ ),
+ ),
+ IconButton(
+ key: const ValueKey('walkthrough.copy'),
+ tooltip: _copied ? 'Command copied' : 'Copy command',
+ onPressed: () => _copy(command),
+ icon: Icon(_copied ? Icons.check : Icons.copy_outlined),
+ ),
+ ],
+ ),
+ ),
+ ),
+ ],
+ );
+ }
+}
diff --git a/app/lib/features/walkthrough/walkthrough_steps.dart b/app/lib/features/walkthrough/walkthrough_steps.dart
new file mode 100644
index 00000000..aa45ea1c
--- /dev/null
+++ b/app/lib/features/walkthrough/walkthrough_steps.dart
@@ -0,0 +1,79 @@
+import 'package:flutter/material.dart';
+
+/// One page of the first-run walkthrough. Pure content: no widgets, so the
+/// copy can be checked without pumping a tree.
+class WalkthroughStep {
+ const WalkthroughStep({
+ required this.icon,
+ required this.title,
+ required this.body,
+ this.points = const [],
+ this.showsHarnessCommand = false,
+ });
+
+ final IconData icon;
+ final String title;
+ final String body;
+
+ /// Short labelled facts shown under the body, one per line.
+ final List points;
+
+ /// Whether this page shows the harness setup command picker.
+ final bool showsHarnessCommand;
+}
+
+/// The agents `pipelines harness setup` accepts, in the order they are offered.
+const harnessAgents = ['claude', 'codex', 'opencode', 'pi'];
+
+/// The command for [agent], exactly as a terminal should run it.
+String harnessSetupCommand(String agent) => 'pipelines harness setup $agent';
+
+/// The four walkthrough pages, in order.
+const walkthroughSteps = [
+ WalkthroughStep(
+ icon: Icons.hub_outlined,
+ title: 'Welcome to Pipelines',
+ body:
+ 'Pipelines runs reusable AI workflows and holds chats with coding '
+ 'agents. Both live on your server, so start by connecting this app '
+ 'to it.',
+ points: [
+ 'Pipelines: workflows you define once and run again.',
+ 'Chats: conversations with coding agents on the server.',
+ 'Connect: open Settings, then Connection, enter the Server URL and '
+ 'choose Connect.',
+ ],
+ ),
+ WalkthroughStep(
+ icon: Icons.build_circle_outlined,
+ title: 'Set up an agent harness',
+ body:
+ 'A harness lets Pipelines drive a coding agent. Choose the agent you '
+ 'use, then run its setup command in a terminal.',
+ showsHarnessCommand: true,
+ ),
+ WalkthroughStep(
+ icon: Icons.play_circle_outline,
+ title: 'Start a run',
+ body:
+ 'Pipelines shows your workflows. Runs shows every run with its '
+ 'progress and results.',
+ points: [
+ 'Pipelines tab: open a workflow and fill in its inputs.',
+ 'Runs tab: follow a run as it works, then read what it produced.',
+ 'Choose Run on a workflow to start one.',
+ ],
+ ),
+ WalkthroughStep(
+ icon: Icons.forum_outlined,
+ title: 'Chat with an agent',
+ body:
+ 'The Chat tab lists your conversations. Open one to read the thread '
+ 'and reply.',
+ points: [
+ 'Float: pop a chat into its own window while you work elsewhere.',
+ 'Terminal: open a terminal beside the Chat tab for direct commands.',
+ 'New chat starts a conversation with an agent.',
+ ],
+ ),
+];
diff --git a/app/lib/features/walkthrough/walkthrough_store.dart b/app/lib/features/walkthrough/walkthrough_store.dart
new file mode 100644
index 00000000..01332fda
--- /dev/null
+++ b/app/lib/features/walkthrough/walkthrough_store.dart
@@ -0,0 +1,118 @@
+import 'package:shared_preferences/shared_preferences.dart';
+
+/// The device-level key for "the first-run walkthrough was finished or skipped".
+/// It is per device, not per server, so a new server never repeats it.
+const String walkthroughSeenKey = 'pipelines.next.firstRunWalkthrough.v1';
+
+/// The key listing the server scopes that were already offered the walkthrough
+/// because they had no pipelines, runs or chats yet.
+const String walkthroughOfferedKey = 'pipelines.next.walkthroughOffered.v1';
+
+/// The persistence seam for the walkthrough. A store that cannot be read or
+/// written reports "seen" and "offered", so an unavailable store never nags.
+abstract interface class WalkthroughStore {
+ Future isSeen();
+
+ Future markSeen();
+
+ Future wasOffered(String serverScope);
+
+ Future markOffered(String serverScope);
+}
+
+Future _openPreferences() async {
+ try {
+ return await SharedPreferences.getInstance();
+ } catch (_) {
+ return null;
+ }
+}
+
+/// `shared_preferences`-backed storage under the `pipelines.next` keys.
+///
+/// [open] is the seam for an unavailable platform store (tests pass one that
+/// yields null); production opens the real preferences.
+class SharedPreferencesWalkthroughStore implements WalkthroughStore {
+ const SharedPreferencesWalkthroughStore({this.open = _openPreferences});
+
+ final Future Function() open;
+
+ Future _preferences() => open();
+
+ @override
+ Future isSeen() async {
+ final preferences = await _preferences();
+ if (preferences == null) return true;
+ try {
+ return preferences.getBool(walkthroughSeenKey) ?? false;
+ } catch (_) {
+ return true;
+ }
+ }
+
+ @override
+ Future markSeen() async {
+ final preferences = await _preferences();
+ if (preferences == null) return;
+ try {
+ await preferences.setBool(walkthroughSeenKey, true);
+ } catch (_) {
+ // Nothing to report: the walkthrough is still dismissed for this run.
+ }
+ }
+
+ @override
+ Future wasOffered(String serverScope) async {
+ final preferences = await _preferences();
+ if (preferences == null) return true;
+ try {
+ final offered = preferences.getStringList(walkthroughOfferedKey);
+ return offered?.contains(serverScope) ?? false;
+ } catch (_) {
+ return true;
+ }
+ }
+
+ @override
+ Future markOffered(String serverScope) async {
+ final preferences = await _preferences();
+ if (preferences == null) return;
+ try {
+ final offered = {
+ ...?preferences.getStringList(walkthroughOfferedKey),
+ serverScope,
+ };
+ await preferences.setStringList(walkthroughOfferedKey, offered.toList());
+ } catch (_) {
+ // A failed write only means the offer may show again later.
+ }
+ }
+}
+
+/// An in-memory store for tests and previews. It never touches the platform
+/// store, so a fixture cannot mark a real device as seen.
+class MemoryWalkthroughStore implements WalkthroughStore {
+ MemoryWalkthroughStore({this.seen = false, Set? offered})
+ : _offered = {...?offered};
+
+ /// Whether the walkthrough is marked seen.
+ bool seen;
+ final Set _offered;
+
+ /// The server scopes already offered the walkthrough.
+ Set get offered => Set.unmodifiable(_offered);
+
+ @override
+ Future isSeen() async => seen;
+
+ @override
+ Future markSeen() async => seen = true;
+
+ @override
+ Future wasOffered(String serverScope) async =>
+ _offered.contains(serverScope);
+
+ @override
+ Future markOffered(String serverScope) async =>
+ _offered.add(serverScope);
+}
diff --git a/app/lib/shell/adaptive_shell.dart b/app/lib/shell/adaptive_shell.dart
index e853a311..14e1fba3 100644
--- a/app/lib/shell/adaptive_shell.dart
+++ b/app/lib/shell/adaptive_shell.dart
@@ -7,10 +7,13 @@ import '../ui/adaptive/floating_destination_bar.dart';
import 'attention_badge.dart';
import 'destination.dart';
import 'list_detail.dart';
+import 'navigation_rail.dart';
+import 'shell_rail_scope.dart';
import 'list_pane_widths.dart';
import 'shell_bar.dart';
import 'shell_chat_shortcut.dart';
import 'shell_list_shortcuts.dart';
+import 'shell_runs_pipelines_shortcut.dart';
import 'shell_search_shortcut_labels.dart';
import 'tab_history.dart';
import '../ui/input/keyboard_owner.dart';
@@ -241,7 +244,8 @@ class _AdaptiveShellState extends State {
);
// The scaffolds below swap the system insets for their bars'
// heights; panes beside a list read the real ones from here.
- final system = MediaQuery.paddingOf(context);
+ final media = MediaQuery.of(context);
+ final system = media.padding;
// A page (Settings) closes to Pipelines on the system Back too; at a
// tab's root Back returns to the tab opened before it. Only with neither
// does Back reach the platform, so Android's (predictive) Back closes the
@@ -255,15 +259,60 @@ class _AdaptiveShellState extends State {
},
child: child,
);
+ // On a wide window the destinations sit in a rail at the left edge, and
+ // the floating bar is not built; the scaffold gets the rest of the window.
+ // The tree has the same shape at every width (an empty rail slot on a
+ // phone), so resizing across the rail's threshold never remounts a
+ // destination.
+ final rail = showsNavigationRail(context);
+ final scaffold = Scaffold(
+ extendBodyBehindAppBar: true,
+ appBar: topBar,
+ body: _destinationStack(contents),
+ extendBody: true,
+ bottomNavigationBar: rail ? null : bar,
+ );
return backable(
ShellSystemInsets(
padding: system,
- child: Scaffold(
- extendBodyBehindAppBar: true,
- appBar: topBar,
- body: _destinationStack(contents),
- extendBody: true,
- bottomNavigationBar: bar,
+ child: Row(
+ crossAxisAlignment: CrossAxisAlignment.stretch,
+ children: [
+ // Badges (running runs, unread chats) rebuild the rail alone.
+ ListenableBuilder(
+ listenable: _bar.badges,
+ builder: (context, _) => rail
+ ? ShellNavigationRail(
+ selected: _selected,
+ icon: (destination) => _icon(
+ destination,
+ destinationDetails(destination).icon,
+ ),
+ onSelected: _select,
+ padding: EdgeInsets.only(
+ top: system.top,
+ bottom: system.bottom,
+ ),
+ )
+ : const SizedBox.shrink(),
+ ),
+ // Three children at every width, so the body keeps its slot.
+ rail
+ ? const VerticalDivider(width: 1, thickness: 1)
+ : const SizedBox.shrink(),
+ Expanded(
+ // Beside the rail the panes lay out in the width the rail leaves,
+ // which the window's width fixes here (not in a layout pass), so
+ // the panes and their pages rebuild with the window.
+ child: ShellRailScope(
+ shown: rail,
+ bodyWidth: rail
+ ? media.size.width - kNavigationRailSpace
+ : null,
+ child: scaffold,
+ ),
+ ),
+ ],
),
),
);
@@ -292,8 +341,9 @@ class _AdaptiveShellState extends State {
}
/// App-wide search and conversation-list selection are handled before text
- /// fields. Split-pane navigation belongs to the chat workspace; tab changes
- /// have no global keyboard chord.
+ /// fields. Split-pane navigation belongs to the chat workspace. Ctrl+A
+ /// bounces between Runs and Pipelines, but leaves text fields and the
+ /// terminal their own Ctrl+A (select all, line start).
bool _handleDestinationKeyEvent(KeyEvent event) {
final keyboard = HardwareKeyboard.instance;
// Ctrl+K is the terminal's kill-line while the terminal has the keyboard;
@@ -303,6 +353,13 @@ class _AdaptiveShellState extends State {
if (event is KeyDownEvent) _openChat();
return true;
}
+ if (shellRunsPipelinesShortcut(event, keyboard)) {
+ if (primaryFocusTakesTyping()) return false;
+ if (event is KeyDownEvent) {
+ _select(shellRunsPipelinesTarget(_selected));
+ }
+ return true;
+ }
// A terminal keeps its keys (Escape, Ctrl+/, Ctrl+digits).
if (primaryFocusIsTypingSurface()) return false;
if (_selected == AppDestination.search &&
diff --git a/app/lib/shell/destination.dart b/app/lib/shell/destination.dart
index a62eb13e..9fe91835 100644
--- a/app/lib/shell/destination.dart
+++ b/app/lib/shell/destination.dart
@@ -2,9 +2,10 @@ import 'package:flutter/material.dart';
enum AppDestination { pipelines, runs, chat, search, settings }
-/// The destinations the shell's tab bar offers, in order. Settings is a
-/// destination the shell can show (its route is `/settings`), but it opens
-/// as a page from the Pipelines bar's gear instead of being a tab.
+/// The destinations the shell's tab bar (or, on a wide window, its rail) offers,
+/// in order. Settings is a destination the shell can show (its route is
+/// `/settings`), but it opens as a page, from the rail's foot on a wide window
+/// or the Pipelines bar's gear on a phone, instead of being a tab.
const List shellTabDestinations = [
AppDestination.pipelines,
AppDestination.runs,
diff --git a/app/lib/shell/list_detail.dart b/app/lib/shell/list_detail.dart
index 13a0a3cd..ce992640 100644
--- a/app/lib/shell/list_detail.dart
+++ b/app/lib/shell/list_detail.dart
@@ -7,6 +7,7 @@ import 'detail_pane_navigator.dart';
import 'list_detail_policy.dart';
import 'list_pane_divider.dart';
import 'list_pane_widths.dart';
+import 'shell_rail_scope.dart';
import 'shell_bar.dart';
export 'list_detail_policy.dart';
@@ -64,7 +65,7 @@ class ListPaneWidth extends StatelessWidget {
builder: (context, constraints) {
final width = split
? listDetailListWidth(
- MediaQuery.sizeOf(context).width,
+ ShellRailScope.windowWidth(context),
constraints.maxWidth,
preferredWidth,
)
@@ -143,7 +144,7 @@ class _ListDetailPanesState extends State {
listenable: widths,
builder: (context, _) => LayoutBuilder(
builder: (context, constraints) {
- final window = media.size.width;
+ final window = ShellRailScope.windowWidth(context);
final available = constraints.maxWidth;
final preferred = widths.widthFor(key);
final resizable =
diff --git a/app/lib/shell/list_detail_policy.dart b/app/lib/shell/list_detail_policy.dart
index ffb1589f..fa760f25 100644
--- a/app/lib/shell/list_detail_policy.dart
+++ b/app/lib/shell/list_detail_policy.dart
@@ -2,6 +2,8 @@ import 'dart:math' as math;
import 'package:flutter/widgets.dart';
+import 'shell_rail_scope.dart';
+
/// At least this wide, a destination keeps its list beside the open item
/// (with the destination rail) instead of pushing the item as its own page.
const double kListDetailMinWidth = 600;
@@ -15,7 +17,7 @@ const double kListPaneMaxWidth = 440;
/// Whether the window at [context] shows list and detail side by side.
bool showsListBesideDetail(BuildContext context) =>
- MediaQuery.sizeOf(context).width >= kListDetailMinWidth;
+ ShellRailScope.windowWidth(context) >= kListDetailMinWidth;
/// The narrowest list pane a drag leaves.
const double kListPaneMinWidth = 240;
diff --git a/app/lib/shell/navigation_rail.dart b/app/lib/shell/navigation_rail.dart
new file mode 100644
index 00000000..93f6deec
--- /dev/null
+++ b/app/lib/shell/navigation_rail.dart
@@ -0,0 +1,145 @@
+import 'package:flutter/material.dart';
+
+import 'destination.dart';
+import 'list_detail_policy.dart';
+
+/// The width of the destination rail on a wide window.
+const double kNavigationRailWidth = 96;
+
+/// The rail with its divider: what the rail takes from a wide window's width.
+const double kNavigationRailSpace = kNavigationRailWidth + 1;
+
+/// The narrowest window that shows the destination rail: the list-detail
+/// minimum for the body beside it, plus the rail and its divider (the space the
+/// shell takes from the window). Narrower windows keep the floating destination
+/// bar, unchanged.
+const double kNavigationRailMinWindowWidth =
+ kListDetailMinWidth + kNavigationRailSpace;
+
+/// Whether the window at [context] shows the destination rail. Read from the
+/// window's own [MediaQuery], so the shell and the floating windows layer
+/// (which sits above the shell) agree.
+bool showsNavigationRail(BuildContext context) =>
+ MediaQuery.sizeOf(context).width >= kNavigationRailMinWindowWidth;
+
+/// The wide layout's left-edge navigation: a Material [NavigationRail] with
+/// an icon and a label per tab, the selected tab marked by the rail's
+/// indicator, and Settings pinned to its bottom.
+///
+/// [icon] builds each tab's icon (its running or unread badge included), so
+/// the rail shows the same counts the floating bar did. [selected] is the
+/// shell's destination: Settings (a page, not a tab) selects no tab but its
+/// own item.
+class ShellNavigationRail extends StatelessWidget {
+ const ShellNavigationRail({
+ super.key,
+ required this.selected,
+ required this.icon,
+ required this.onSelected,
+ this.padding = EdgeInsets.zero,
+ });
+
+ final AppDestination selected;
+ final Widget Function(AppDestination destination) icon;
+ final ValueChanged onSelected;
+
+ /// The system insets the rail keeps clear of: the status bar above and the
+ /// navigation bar below.
+ final EdgeInsets padding;
+
+ @override
+ Widget build(BuildContext context) {
+ final index = shellTabDestinations.indexOf(selected);
+ return Padding(
+ padding: padding,
+ child: SizedBox(
+ width: kNavigationRailWidth,
+ child: NavigationRail(
+ key: const ValueKey('shell.navigation-rail'),
+ minWidth: kNavigationRailWidth,
+ labelType: NavigationRailLabelType.all,
+ selectedIndex: index < 0 ? null : index,
+ onDestinationSelected: (value) =>
+ onSelected(shellTabDestinations[value]),
+ destinations: [
+ for (final destination in shellTabDestinations)
+ NavigationRailDestination(
+ icon: KeyedSubtree(
+ key: ValueKey('shell.destination.${destination.name}'),
+ // The bar it replaces named each tab in a tooltip too.
+ child: Tooltip(
+ message: destinationDetails(destination).label,
+ child: icon(destination),
+ ),
+ ),
+ label: Text(destinationDetails(destination).label),
+ ),
+ ],
+ trailingAtBottom: true,
+ trailing: _SettingsRailItem(
+ selected: selected == AppDestination.settings,
+ onTap: () => onSelected(AppDestination.settings),
+ ),
+ ),
+ ),
+ );
+ }
+}
+
+/// Settings at the rail's foot, drawn as a [NavigationRailDestination] is: an
+/// icon on a stadium indicator with its label under it, and the same colours.
+/// It is not a [NavigationRailDestination] itself because the rail's
+/// destination list is the tabs, and `trailing` is what the rail pins.
+class _SettingsRailItem extends StatelessWidget {
+ const _SettingsRailItem({required this.selected, required this.onTap});
+
+ final bool selected;
+ final VoidCallback onTap;
+
+ @override
+ Widget build(BuildContext context) {
+ final scheme = Theme.of(context).colorScheme;
+ final item = destinationDetails(AppDestination.settings);
+ final foreground = selected
+ ? scheme.onSecondaryContainer
+ : scheme.onSurfaceVariant;
+ final textStyle = Theme.of(context).textTheme.labelMedium?.copyWith(
+ color: foreground,
+ fontWeight: selected ? FontWeight.w600 : FontWeight.w500,
+ );
+ return Semantics(
+ button: true,
+ selected: selected,
+ label: item.label,
+ child: ExcludeSemantics(
+ child: InkWell(
+ key: const ValueKey('shell.destination.settings'),
+ onTap: onTap,
+ child: SizedBox(
+ width: kNavigationRailWidth,
+ child: Padding(
+ padding: const EdgeInsets.symmetric(vertical: 12),
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [
+ Container(
+ width: 56,
+ height: 32,
+ alignment: Alignment.center,
+ decoration: ShapeDecoration(
+ shape: const StadiumBorder(),
+ color: selected ? scheme.secondaryContainer : null,
+ ),
+ child: Icon(item.icon, color: foreground),
+ ),
+ const SizedBox(height: 4),
+ Text(item.label, style: textStyle),
+ ],
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+}
diff --git a/app/lib/shell/shell_rail_scope.dart b/app/lib/shell/shell_rail_scope.dart
new file mode 100644
index 00000000..024f0a28
--- /dev/null
+++ b/app/lib/shell/shell_rail_scope.dart
@@ -0,0 +1,35 @@
+import 'package:flutter/widgets.dart';
+
+/// Marks the content beside the destination rail. A wide window's content
+/// lays out in the width left beside the rail, so list and detail panes read
+/// that width ([windowWidth]) instead of the window's. Outside the scope (a
+/// phone, a route pushed over the shell) the window's own width applies.
+class ShellRailScope extends InheritedWidget {
+ const ShellRailScope({
+ super.key,
+ required this.shown,
+ required this.bodyWidth,
+ required super.child,
+ });
+
+ /// Whether the rail is shown beside this content.
+ final bool shown;
+
+ /// The width beside the rail; null when no rail is shown.
+ final double? bodyWidth;
+
+ /// Whether the rail is shown beside [context]'s content.
+ static bool isShown(BuildContext context) =>
+ context.dependOnInheritedWidgetOfExactType()?.shown ??
+ false;
+
+ /// The width the panes of [context] lay out in: the body beside the rail,
+ /// or else the window.
+ static double windowWidth(BuildContext context) =>
+ context.dependOnInheritedWidgetOfExactType()?.bodyWidth ??
+ MediaQuery.sizeOf(context).width;
+
+ @override
+ bool updateShouldNotify(ShellRailScope oldWidget) =>
+ shown != oldWidget.shown || bodyWidth != oldWidget.bodyWidth;
+}
diff --git a/app/lib/shell/shell_runs_pipelines_shortcut.dart b/app/lib/shell/shell_runs_pipelines_shortcut.dart
new file mode 100644
index 00000000..ad25a0eb
--- /dev/null
+++ b/app/lib/shell/shell_runs_pipelines_shortcut.dart
@@ -0,0 +1,28 @@
+import 'package:flutter/services.dart';
+
+import 'destination.dart';
+
+/// The chord that bounces between Runs and Pipelines, as the help page reads
+/// it. It is the same on every platform.
+const shellRunsPipelinesShortcutLabel = 'Ctrl+A';
+
+/// Whether [event] is Ctrl+A. Only Ctrl counts: Alt, Shift, Cmd and chords
+/// with both Ctrl and Alt are not the shortcut. Repeats of a held chord match
+/// as well, so the caller can swallow them; only its first press acts.
+bool shellRunsPipelinesShortcut(KeyEvent event, HardwareKeyboard keyboard) {
+ if (event is KeyUpEvent ||
+ keyboard.isAltPressed ||
+ keyboard.isShiftPressed ||
+ keyboard.isMetaPressed ||
+ !keyboard.isControlPressed) {
+ return false;
+ }
+ return event.logicalKey == LogicalKeyboardKey.keyA;
+}
+
+/// The destination Ctrl+A goes to from [current]: Pipelines from Runs, and
+/// Runs from every other destination (Pipelines included).
+AppDestination shellRunsPipelinesTarget(AppDestination current) =>
+ current == AppDestination.runs
+ ? AppDestination.pipelines
+ : AppDestination.runs;
diff --git a/app/lib/shell/windows/window_entry.dart b/app/lib/shell/windows/window_entry.dart
index 83fe7afe..1d36b154 100644
--- a/app/lib/shell/windows/window_entry.dart
+++ b/app/lib/shell/windows/window_entry.dart
@@ -37,7 +37,7 @@ class WindowEntry {
/// The saved frame; it is drawn fitted inside the window area.
final Rect frame;
- /// Hidden by its minimise button; still listed and shown again with its
+ /// Hidden by the title bar's X; still listed and shown again with its
/// group.
final bool minimized;
final bool maximized;
diff --git a/app/lib/shell/windows/window_frame.dart b/app/lib/shell/windows/window_frame.dart
index 61240ef6..bce9e305 100644
--- a/app/lib/shell/windows/window_frame.dart
+++ b/app/lib/shell/windows/window_frame.dart
@@ -11,8 +11,9 @@ double windowTitleBarHeight(BuildContext context) =>
MediaQuery.textScalerOf(context).scale(40).clamp(40.0, 64.0);
/// A floating window's card and title bar: the title (drag to move, double
-/// click to maximise), the kind's actions, then Minimise, Maximise and
-/// Close. The content is drawn over the card's body by the window's
+/// click to maximise), the kind's actions, then Maximise and the X. The X
+/// minimises: it hides the window and keeps its state, like the chord does
+/// in reverse. The content is drawn over the card's body by the window's
/// navigator.
class WindowFrame extends StatelessWidget {
const WindowFrame({
@@ -25,7 +26,6 @@ class WindowFrame extends StatelessWidget {
required this.onMoveEnd,
required this.onMinimize,
required this.onToggleMaximized,
- required this.onClose,
});
final String title;
@@ -36,9 +36,10 @@ class WindowFrame extends StatelessWidget {
/// The drag's delta and the pointer's global position.
final void Function(Offset delta, Offset globalPosition) onMove;
final VoidCallback onMoveEnd;
+
+ /// The X: hides the window, keeping it listed and its state.
final VoidCallback onMinimize;
final VoidCallback onToggleMaximized;
- final VoidCallback onClose;
@override
Widget build(BuildContext context) {
@@ -69,11 +70,6 @@ class WindowFrame extends StatelessWidget {
onPressed: action.onPressed,
icon: Icon(action.icon),
),
- IconButton(
- tooltip: 'Minimise',
- onPressed: onMinimize,
- icon: const Icon(Icons.minimize),
- ),
IconButton(
tooltip: maximized ? 'Restore size' : 'Maximise',
onPressed: onToggleMaximized,
@@ -82,8 +78,8 @@ class WindowFrame extends StatelessWidget {
),
),
IconButton(
- tooltip: 'Close',
- onPressed: onClose,
+ tooltip: 'Minimise',
+ onPressed: onMinimize,
icon: const Icon(Icons.close),
),
const SizedBox(width: 4),
diff --git a/app/lib/shell/windows/window_host.dart b/app/lib/shell/windows/window_host.dart
index f4fc1f84..682d9b4b 100644
--- a/app/lib/shell/windows/window_host.dart
+++ b/app/lib/shell/windows/window_host.dart
@@ -1,6 +1,7 @@
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
+import '../navigation_rail.dart';
import 'window_focus.dart';
import 'window_layer.dart';
import 'window_manager.dart';
@@ -18,7 +19,16 @@ import 'window_shortcuts.dart';
///
/// The host fills its parent and takes no input between windows.
class WindowHost extends StatefulWidget {
- const WindowHost({super.key, required this.manager});
+ const WindowHost({
+ super.key,
+ required this.manager,
+ this.reservesRail = false,
+ });
+
+ /// Whether the shell beside this host shows the destination rail on the
+ /// window's left edge; the windows then keep to the right of it while the
+ /// window is wide enough for the rail (see [showsNavigationRail]).
+ final bool reservesRail;
final WindowManager manager;
@@ -119,24 +129,36 @@ class _WindowHostState extends State {
]),
builder: (context, _) => LayoutBuilder(
builder: (context, constraints) {
- final bounds = constraints.biggest;
- return Stack(
- fit: StackFit.expand,
- children: [
- for (final entry in windows)
- if (manager.kinds[entry.kind] case final kind?)
- WindowLayer(
- key: ValueKey(entry.id),
- manager: manager,
- kind: kind,
- entry: entry,
- visible:
- manager.isVisible(entry) &&
- bounds.width >= kind.minHostWidth,
- bounds: bounds,
- focus: _focus,
- ),
- ],
+ // Beside the destination rail the windows keep to the page's
+ // right, so they never sit under the rail.
+ // The shell takes the rail and its divider (kNavigationRailSpace).
+ final leading = widget.reservesRail && showsNavigationRail(context)
+ ? kNavigationRailSpace
+ : 0.0;
+ final bounds = Size(
+ constraints.maxWidth - leading,
+ constraints.maxHeight,
+ );
+ return Padding(
+ padding: EdgeInsetsDirectional.only(start: leading),
+ child: Stack(
+ fit: StackFit.expand,
+ children: [
+ for (final entry in windows)
+ if (manager.kinds[entry.kind] case final kind?)
+ WindowLayer(
+ key: ValueKey(entry.id),
+ manager: manager,
+ kind: kind,
+ entry: entry,
+ visible:
+ manager.isVisible(entry) &&
+ bounds.width >= kind.minHostWidth,
+ bounds: bounds,
+ focus: _focus,
+ ),
+ ],
+ ),
);
},
),
diff --git a/app/lib/shell/windows/window_kind.dart b/app/lib/shell/windows/window_kind.dart
index 3a98499d..2f287885 100644
--- a/app/lib/shell/windows/window_kind.dart
+++ b/app/lib/shell/windows/window_kind.dart
@@ -2,7 +2,7 @@ import 'package:flutter/widgets.dart';
import 'window_entry.dart';
-/// One action in a window's title bar, before Minimise and Close (Dock on a
+/// One action in a window's title bar, before Maximise and the X (Dock on a
/// chat, a kind's own menu).
class WindowAction {
const WindowAction({
@@ -42,7 +42,7 @@ abstract class WindowKind {
/// The window's content, below the title bar.
Widget build(BuildContext context, WindowEntry entry);
- /// Title-bar actions before Minimise and Close.
+ /// Title-bar actions before Maximise and the X.
List actions(BuildContext context, WindowEntry entry) =>
const [];
@@ -57,7 +57,7 @@ abstract class WindowKind {
/// as its window takes focus. The default leaves it on the window.
void focusContent(WindowEntry entry) {}
- /// Called after the user closes the window (the X).
+ /// Called after the window is closed (Dock, Close all, a chat's /close).
void closed(WindowEntry entry) {}
/// Validates a saved window's [WindowEntry.data]; null drops the window.
diff --git a/app/lib/shell/windows/window_layer.dart b/app/lib/shell/windows/window_layer.dart
index efaffc28..427e2847 100644
--- a/app/lib/shell/windows/window_layer.dart
+++ b/app/lib/shell/windows/window_layer.dart
@@ -259,7 +259,6 @@ class _WindowLayerState extends State
onMinimize: () => manager.setMinimized(_id, true),
onToggleMaximized: () =>
manager.setMaximized(_id, !entry.maximized),
- onClose: () => manager.close(_id),
),
),
),
diff --git a/app/lib/ui/motion/container_transform_flight.dart b/app/lib/ui/motion/container_transform_flight.dart
index f8a1b377..6dbead2e 100644
--- a/app/lib/ui/motion/container_transform_flight.dart
+++ b/app/lib/ui/motion/container_transform_flight.dart
@@ -229,11 +229,14 @@ class _Frame {
required bool tracking,
}) {
const curve = Curves.fastOutSlowIn;
- // Played backwards in time, the same easing reads as the item settling.
+ // Closing reads `t` from 1 to 0, so easeIn of `t` is a shrink that
+ // decelerates in time and starts on the first frame. The time-reversed
+ // fastOutSlowIn barely moved for its first ~60 ms, which read as Back
+ // doing nothing.
final grown = tracking
? t
: closing
- ? curve.flipped.transform(t)
+ ? Curves.easeInCubic.transform(t)
: curve.transform(t);
// Opening covers the item first and shows the page late; closing hides
// the page first and uncovers the item late.
diff --git a/app/notes/android-background-delivery-reliability.md b/app/notes/android-background-delivery-reliability.md
new file mode 100644
index 00000000..d3b29b9c
--- /dev/null
+++ b/app/notes/android-background-delivery-reliability.md
@@ -0,0 +1,91 @@
+# Android background delivery: survive Doze, sign-in, battery, diagnosis
+
+Stage 01-implement, run 20261112-0157. Source only; not committed, not installed.
+
+## What changed
+
+- **Reconnects are alarms, not handler delays.** `ReconnectAlarms` schedules
+ `setExactAndAllowWhileIdle` when `canScheduleExactAlarms()`, otherwise
+ `setAndAllowWhileIdle`. The alarm PendingIntent is a foreground-service intent
+ to `NotificationService` (`ACTION_RECONNECT`). The `Handler.postDelayed`
+ reconnect is gone.
+- **Watchdog.** `NotificationWatchdog` (JobScheduler, periodic 15 min,
+ persisted) restarts the service when delivery is enabled and the socket is
+ down with no reconnect pending. It does not restart while signed out or
+ waiting for a network. Also scheduled by `NotificationService.start`.
+- **Connect wake lock.** `ConnectWakeLock` holds a partial wake lock for 30 s
+ from `connect()` until the socket opens or fails.
+- **Swipe away.** `onTaskRemoved` logs and queues a watchdog check 2 s later.
+- **Battery exemption.** `SettingsDeviceDeliverySection` shows a persistent
+ warning row while delivery is on and the exemption is missing, with the
+ Samsung "Never sleeping apps" note. `setEnabled(true)` requests the
+ exemption before starting the service. Opening Settings with delivery already
+ on and the exemption missing asks once per open (`NotificationServiceController.open`);
+ resume refreshes never ask again.
+- **HTTP 401/403.** The retry loop stops, status becomes `sign_in_required`,
+ and a "Sign in to Pipelines again to keep notifications" notice is posted
+ (channel `pipelines.account`, id 2). `configure` with a fresh cookie restarts
+ the service.
+- **Connection log.** `ConnectionLog` keeps the last 50 events (time, event,
+ error, HTTP code) in the service preferences. The channel method
+ `connectionEvents` returns them. Settings shows them in an expandable
+ "Connection log" row.
+
+## Files
+
+- Kotlin (new): `ReconnectPolicy.kt`, `ReconnectAlarms.kt`,
+ `NotificationWatchdog.kt`, `ConnectWakeLock.kt`, `ConnectionLog.kt`
+- Kotlin (changed): `NotificationService.kt`, `NotificationPresenter.kt`,
+ `NotificationServiceChannel.kt`, `ServiceSettings.kt`, `AndroidManifest.xml`
+ (WAKE_LOCK, SCHEDULE_EXACT_ALARM, watchdog service)
+- Kotlin tests (new): `ConnectionLogTest.kt` (5), `ReconnectPolicyTest.kt` (3)
+- Dart (new): `lib/features/notification_service/notification_service_events.dart`
+- Dart (changed): `notification_service_bridge.dart`,
+ `notification_service_controller.dart`, `notification_service_status.dart`,
+ `lib/features/settings/settings_device_delivery_section.dart`
+- Dart tests (changed): `test/features/settings/settings_device_delivery_section_test.dart`
+ (+8 cases), `test/features/notification_service/notification_service_bridge_test.dart`
+ (+3 cases), `test/features/notification_service/fake_notification_service.dart`
+
+## Focused results
+
+- Kotlin: `gradle :app:testDebugUnitTest --tests 'net.awan.pipelines_app.notify.*'`
+ BUILD SUCCESSFUL. 28 of 28 pass: ConnectionLogTest 5, ReconnectPolicyTest 3,
+ DeliveryLedgerTest 8, NotificationProtocolTest 12. Includes main-source compile.
+- Flutter: `tool/memwatch/full.sh` on the four files below, PASS 35 passed,
+ 0 failed (run twice, once after formatting):
+ - test/features/settings/settings_device_delivery_section_test.dart
+ - test/features/notification_service/notification_service_bridge_test.dart
+ - test/features/notification_service/notification_service_handoff_test.dart
+ - test/features/attention/notify/notification_delivery_test.dart
+- `tool/analyze.sh`: clean (run twice).
+
+## Affected UI states (for ui-review, not captured here)
+
+- Delivery on, exemption missing: warning row visible with Samsung note.
+- Delivery on, exemption granted: warning row gone; battery row says "Allowed".
+- Delivery off: no battery row, no warning row.
+- Status "Sign in to Pipelines again to keep notifications".
+- Connection log collapsed, expanded with events, expanded empty
+ ("No connection events yet"). Expansion needs an interactive check.
+
+## Limitations and decisions
+
+- **Not verified on a device.** Doze timing, alarm delivery, the
+ foreground-start exemption from alarms and the watchdog job, the swipe
+ restart, and the sign-in notice were not run. The Fold was not touched.
+- **Exact alarms.** SCHEDULE_EXACT_ALARM is declared, but the app does not
+ send the user to grant it. Without the grant, reconnects use
+ idle-tolerant alarms.
+- **Upgrade users are prompted when Settings opens, not at app start.** The
+ exemption is requested on switch-on, and on opening Settings while delivery
+ is on and the exemption is missing. The prompt is not fired from app start
+ because the section is the only place with the request context. A user who
+ declines is prompted again the next time Settings opens, then sees the
+ warning row. Users who never open Settings are not prompted.
+- **JobScheduler is deferred in Doze**, so the watchdog is a backstop; the
+ alarms are the primary path.
+- NotificationService.kt is 387 lines (aim is under 250; it was 293 before).
+ The reconnect alarms, watchdog, wake lock and log are in separate files,
+ but the socket state machine remains in the service; splitting it further is
+ a follow-up.
diff --git a/app/notes/chat-back-start.md b/app/notes/chat-back-start.md
new file mode 100644
index 00000000..5a6d17be
--- /dev/null
+++ b/app/notes/chat-back-start.md
@@ -0,0 +1,54 @@
+# Chat Back starts immediately (phone)
+
+## Finding
+
+Static reading of the phone chat path (`DetailPageHost`, `ContainerTransformPageRoute`,
+`ContainerTransformFlight`, the chat screen's `_back`, the shell's back handling) found no
+awaited work before the pop. Draft, scroll and transcript saves run fire-and-forget or in
+`dispose`, after the reverse animation. `DetailPageHost`'s `onClosed` runs when the route is
+disposed, so it cannot delay the pop.
+
+The delay the user sees is the close curve. Closing used `Curves.fastOutSlowIn.flipped`
+against the animation value, which barely moves for its first ~60 ms. The page sat still
+after Back, then began to shrink.
+
+## Change
+
+`lib/ui/motion/container_transform_flight.dart`: the closing shrink uses
+`Curves.easeInCubic.transform(t)` on the reverse animation value. That is a shrink that starts
+on the first frame and decelerates into the row. Opening is unchanged. The reverse duration
+stays at `Motion.containerTransformReverse` = 250 ms (≤300 ms).
+
+## Measured (widget test, fake frame clock, 390x844, 16 ms per frame)
+
+Share of the page's shrink travel completed after each frame following the system Back
+(`handlePopRoute` then `pump`). The first frame after the pop only starts the ticker, so it
+reads 0 in both builds.
+
+| Elapsed after pop | Before | After |
+| --- | ---: | ---: |
+| 16 ms | 0.0% | 0.0% |
+| 32 ms | 1.0% | 15.7% |
+| 48 ms | 4.6% | 30.7% |
+| 64 ms | 12.1% | 44.1% |
+| 80 ms | 25.2% | 56.4% |
+
+The Back route is no longer current, and its animation is `reverse`, after the first pump
+in both builds. Route change was already synchronous.
+
+## Focused tests
+
+Command: `tool/memwatch/full.sh 'test/ui/motion/container_transform_back_start_test.dart test/ui/motion/container_transform_route_test.dart test/shell/detail_page_test.dart test/features/chat/chat_open_transition_test.dart'`
+Result: 15 passed, 0 failed (peak 1284 MB, 11 s).
+
+- New regression `container_transform_back_start_test.dart`: system Back changes the route
+ in one pump, and the page is more than 10% shrunk 16 ms later. The owner's close work
+ awaits a future that never completes, and Back still starts. Against the old curve this
+ test fails (shrink 0.99%).
+- `tool/analyze.sh`: clean.
+
+## Not verified
+
+- `tool/chat_back_latency_probe.mjs` (browser) was not run; UI capture belongs to ui-review.
+- Phone device timing was not measured (no device test ran).
+- Leaving the chat list (tab-root Back) was read, not measured: it calls `_select` synchronously.
diff --git a/app/notes/chat-floating-pane.md b/app/notes/chat-floating-pane.md
index e17dcb38..684f0da1 100644
--- a/app/notes/chat-floating-pane.md
+++ b/app/notes/chat-floating-pane.md
@@ -15,13 +15,14 @@ every destination and come back at app start without Chat being opened.
chat's window last was, else at the default frame stepped 32 px per chat
window already open.
- **Window**: drag the title bar to move, the lower right corner to resize,
- double click the title to maximise. The title bar has Dock, Minimise,
- Maximise and Close.
+ double click the title to maximise. The title bar has Dock, Maximise and
+ the X.
- **Dock** puts the chat back into the tiling, right of the active pane. When
the Chat destination is not built it opens the chat there instead.
- - **Minimise** hides that window; the chord brings it back.
- - **Close (X)** closes the window and returns nothing to the tiling. The chat
- itself is not closed on the server.
+ - **X** (tooltip and semantics: Minimise) hides that window, keeping its state;
+ it stays listed in the Windows menu and the chord brings it back. It never
+ closes the window, the chat or the tiling: nothing returns to the tiling.
+ The chat itself is not closed on the server.
- **Chord**: Alt+Y, Ctrl+Y, and Cmd+Y on Apple platforms (`chatFloatShortcut`).
With chat windows open it hides or shows all of them. With none it floats the
active tiled pane, when that pane can float and Chat has the keyboard;
@@ -29,14 +30,25 @@ every destination and come back at app start without Chat being opened.
terminal). On macOS Ctrl+Y in a terminal always goes to the shell.
- **Focus**: a window that shows or comes to the top puts the keyboard in its
composer; hiding the last window gives it back to what had it.
-- **Cycle**: while a floating chat window's content holds the keyboard (a
- composer, a Files page inside it), Ctrl+Tab brings the next visible chat
- window to the top and Ctrl+Shift+Tab the previous one, wrapping round. The
- order is the stacking order, bottom to top, and the window's composer takes
- the keyboard. Command+Tab stays with the system. With the tiling focused,
- Ctrl+Tab still cycles its panes; while the terminal claims tab keys (shown)
- it switches terminal tabs. Alt+` (`windowCycleShortcut`) still cycles every
- kind of window, not only chats.
+- **Cycle**: Ctrl+Tab and Ctrl+Shift+Tab move between the chats the user can
+ see, and never bring up one that is not shown.
+ - **While any chat window is shown** (not minimised, its group shown), the
+ keys cycle those windows only, from wherever the keyboard is in Chat: a
+ window's composer, a Files page inside it, or the tiling (the chat list
+ included). From a window, the next (previous) shown window in open order
+ comes to the top, wrapping round. From the tiling, Ctrl+Tab takes the
+ top-most shown window to the top first. Either way the window's composer
+ takes the keyboard. Open order is the order the windows were opened (a
+ restored window keeps its saved place), so a raise does not change the
+ cycle; the stacking order does change on a raise.
+ - **With no chat window shown**, Ctrl+Tab cycles the tiled panes only and
+ the keys focus the chosen pane's composer. With one tiled pane it does
+ nothing. A chat shown before, or a minimised or floating chat, is never
+ swapped in.
+ - Command+Tab stays with the system. While the terminal claims tab keys
+ (shown) Ctrl+Tab switches terminal tabs. A keyboard held by another window
+ (a run, terminal) is left to that window. Alt+` (`windowCycleShortcut`)
+ still cycles every kind of window, not only chats.
- **Popups**: sheets, dialogs, menus and tooltips opened from a floating chat
are above every window. Files opens as a page inside the window, and a file
opened from it stays in the window. Because the window's own title bar names
@@ -68,17 +80,36 @@ every destination and come back at app start without Chat being opened.
## Checks
-- Focused, 2026-11-12, `tool/memwatch/full.sh` with
- `test/features/chat/chat_floating_pane_test.dart` and
- `test/features/terminal/terminal_chat_tab_test.dart`: 16 passed, 0 failed.
- New in the first: Ctrl+Tab and Ctrl+Shift+Tab over three floating chats
- (order, wrap, composer focus, Command+Tab ignored); with the tiling focused
- Ctrl+Tab moves the active pane and leaves the windows alone, and with one
- window focused it does nothing; a terminal that claims tab keys keeps
- Ctrl+Tab over a focused chat window.
-- `tool/analyze.sh` on the changed paths: clean.
-- Affected states: two or more floating chats; one floating chat; tiling
- focused; a window focused with the terminal shown (claimed); Command+Tab.
+- Focused, 2026-11-12, `tool/memwatch/full.sh` over
+ `test/features/chat/chat_floating_pane_test.dart`,
+ `test/features/chat/chat_keyboard_focus_test.dart`,
+ `test/features/chat/chat_control_tab_test.dart`,
+ `test/features/chat/windows/chat_windows_test.dart` and
+ `test/features/terminal/terminal_chat_tab_test.dart`: 38 passed, 0 failed.
+ Related Ctrl+Tab users, `tool/memwatch/full.sh` over
+ `test/shell/destination_shortcuts_test.dart`,
+ `test/shell/tab_history_back_test.dart`, `test/shell/search_escape_test.dart`
+ and `test/features/chat/shell/chat_shell_terminal_test.dart`: 26 passed,
+ 0 failed.
+- New in the first file: Ctrl+Tab and Ctrl+Shift+Tab over three floating chats
+ cycle in open order, not stacking order (order, wrap, composer focus,
+ Command+Tab ignored). With the tiling focused Ctrl+Tab goes to the top-most
+ shown window and leaves the panes alone; with one shown window it does
+ nothing; with the window minimised the panes cycle and the window stays
+ hidden. With one tiled pane and a minimised chat, Ctrl+Tab does nothing and
+ shows nothing. A terminal that claims tab keys keeps Ctrl+Tab over a focused
+ chat window.
+- Removed: the single-pane recent-chat swap (the chat shown before, opened
+ back into the pane), with its tests in `chat_keyboard_focus_test.dart`. A
+ single pane with no shown window now does nothing on Ctrl+Tab, so
+ `chat_control_tab_test.dart` no longer expects the composer to take focus
+ from the sidebar.
+- `tool/analyze.sh` on `lib/features/chat` and the three chat test files:
+ clean.
+- Affected states: two or more floating chats; one floating chat shown;
+ floating chat minimised with one tiled pane; tiling focused with windows
+ shown and with none; a window focused; the terminal shown (claimed);
+ Command+Tab.
- Not covered: the terminal's own tab switching (the test app has no terminal
surface), real browser or device keys, and captures (ui-review's).
- Observed, not changed: in the widget harness, floating from a pane's More
diff --git a/app/notes/chat-terminal-buttons.md b/app/notes/chat-terminal-buttons.md
new file mode 100644
index 00000000..cd428a89
--- /dev/null
+++ b/app/notes/chat-terminal-buttons.md
@@ -0,0 +1,76 @@
+# Chat terminal buttons (narrow duplicate, bar styling)
+
+## Findings (from the code and the ui-review captures)
+
+- The terminal toggle is the shell's bar action, passed as `barActions` from
+ `application/pipelines_app.dart` on the Chat tab. The shell draws that bar
+ only where it is not covered:
+ - Wide (>= 600, `kListDetailMinWidth`): the shell bar sits over the list
+ column while a chat is open, so the terminal shows there beside New chat
+ and Refresh (capture: `Terminal (Option+T)` at x 287). The chat's own bar
+ holds only Files and More.
+ - Narrow (< 600): the open chat is a pushed page with its own bar
+ (`ShellBar(barless: true)`), which covers the shell bar. A shell-bar
+ terminal button therefore never shows on a phone chat, even though it was
+ listed in `barActions`. This is why the first attempt (keeping it in
+ `barActions` for an open chat) rendered nothing on phone.
+ - Narrow chat list: the shell bar shows the toggle beside New chat and
+ Refresh (the duplicate this change removes).
+- The styling difference: `TerminalToggleButton` passed `isSelected: shown`,
+ which tints the icon while the terminal is shown. Files and More
+ (`ChatBarAction`, `SegmentedMoreButton`) are plain IconButtons with no
+ selected state.
+
+## Changes
+
+- `lib/application/app_terminals.dart`: `barToggle(context)` returns the shell
+ toggle only on a wide layout; null on narrow (chat list and open chat).
+- `lib/application/pipelines_app.dart`: the Chat tab's `barActions` uses
+ `?_terminals.barToggle(context)`.
+- `lib/features/terminal/terminal_open_action.dart`: new
+ `terminalChatBarAction(context)`: on narrow, with a terminal surface, a
+ `ChatBarAction` (the same widget as Files) that toggles the terminal
+ (identifier `chat-terminal-toggle`). Null on wide or without a surface.
+- `lib/features/chat/conversation/chat_thread_view.dart`: the chat header's
+ actions are Files followed by `?terminalChatBarAction(context)`, so a
+ narrow open chat shows the terminal beside Files.
+- `lib/features/terminal/terminal_toggle_button.dart`: drops `isSelected`; the
+ shown state is exposed as `Semantics(toggled:)` only.
+
+## Tests
+
+- `test/application/app_terminals_test.dart`: wide 1000 px offers the shell
+ toggle; narrow 390 px offers none.
+- `test/features/terminal/terminal_chat_bar_action_test.dart`, light and dark:
+ phone 390 px: the chat bar's terminal button is present, the same size as
+ Files, the same icon colour, not selected, and tapping it toggles the
+ terminal; wide 1000 px and no terminal surface: no chat-bar terminal button.
+- `test/features/terminal/terminal_toggle_button_test.dart`, light and dark:
+ the shell's terminal button has no `isSelected`, its icon colour equals
+ Files' in hidden and shown states, both are 48 px, and the shown state is
+ announced as toggled.
+- Affected users re-run: `terminal_first_open_test.dart`,
+ `terminal_surface_test.dart`, `chat_floating_chrome_test.dart`,
+ `chat_floating_pane_test.dart`.
+
+## Focused results
+
+`tool/memwatch/full.sh` with the seven paths above as one argument:
+57 passed, 0 failed (peak 1877 MB, 53 s; verdict names only those paths).
+`tool/analyze.sh`: clean.
+
+## Expected states (from the code; not captured here)
+
+- Phone chat list: no terminal in the bar; the shortcut bubble remains.
+- Phone open chat: the chat bar reads Files, terminal, More; the terminal is
+ the same 48 px plain IconButton style as Files.
+- Wide chat list and wide open chat: placement unchanged; the shell bar's
+ terminal button is plain (no selected tint).
+
+## Not verified here
+
+- Rendered states at phone and desktop sizes, light and dark, and hover and
+ pressed states: not captured (ui-review owns captures).
+- `pipelines_app.dart` wiring has no direct test.
+ `test/application/pipelines_app_test.dart` fails on untouched main (pending
+ launch-update timer), so it was not run.
diff --git a/app/notes/ctrl-a-runs-pipelines.md b/app/notes/ctrl-a-runs-pipelines.md
new file mode 100644
index 00000000..6a6ae0dd
--- /dev/null
+++ b/app/notes/ctrl-a-runs-pipelines.md
@@ -0,0 +1,37 @@
+# Ctrl+A toggles Runs and Pipelines
+
+Stage 01-implement (artifact 401). Not committed.
+
+## Behaviour
+- Ctrl+A (the same chord on every platform) moves the shell between destinations:
+ - from Runs, to Pipelines;
+ - from Pipelines, to Runs;
+ - from any other destination (Chat, Search, Settings), to Runs.
+- It is matched like Ctrl+K in `shell/adaptive_shell.dart`: logical key A with Ctrl alone. Alt, Shift, Cmd, Ctrl+Alt, and key-up events do not match. Repeats of a held chord are swallowed; only the first key-down acts.
+- It does not act while a text field (`primaryFocusTakesTyping`) or a `TypingSurface` such as the terminal has focus. The handler returns false, so the field or terminal keeps Ctrl+A (select all, line start).
+- The switch goes through the shell's normal `_select`, so a controlled shell (`onDestinationSelected`) receives the destination.
+
+## Changed paths
+- `app/lib/shell/shell_runs_pipelines_shortcut.dart` (new): `shellRunsPipelinesShortcut` (matcher), `shellRunsPipelinesTarget` (destination rule), `shellRunsPipelinesShortcutLabel` (`'Ctrl+A'`).
+- `app/lib/shell/adaptive_shell.dart`: one branch in `_handleDestinationKeyEvent`, after the Ctrl+K branch and before the typing-surface check; updated doc comment.
+- `app/lib/features/settings/keyboard_shortcuts_registry.dart`: "Switch between Runs and Pipelines" help entry, `Ctrl+A` on every platform, with a caveat about text fields and the terminal.
+- `app/test/shell/runs_pipelines_shortcut_test.dart` (new): matcher, destination rule, Chat→Runs→Pipelines→Runs sequence, text-field exception, terminal exception.
+- `app/test/features/settings/keyboard_shortcuts_help_test.dart`: help entry test over every `TargetPlatform` value.
+
+## Focused results
+- `tool/memwatch/full.sh 'test/shell/runs_pipelines_shortcut_test.dart test/features/settings/keyboard_shortcuts_help_test.dart test/shell/shell_chat_shortcut_test.dart test/shell/destination_shortcuts_test.dart'`: PASS, 19 passed, 0 failed, peak 1151 MB, 13s, exit 0.
+- Mutation check: with the `primaryFocusTakesTyping()` guard removed, `runs_pipelines_shortcut_test.dart` fails (2 failed, including the text-field case). The guard was restored; the file matches the pre-mutation backup.
+- `tool/analyze.sh` on the changed files: clean, exit 0. Run after the focused tests, sequentially.
+- No existing test sends Ctrl+A. The `keyA` uses in `chat_shell_terminal_test.dart` and `chat_transcript_selection_test.dart` are plain or Cmd+A, so they are unaffected.
+
+## Affected states
+- Shell tabs: Pipelines, Runs, Chat, Search, and Settings (a page of Pipelines).
+- Text field focused: Ctrl+A goes to the field.
+- Terminal focused: Ctrl+A goes to the terminal.
+- Help page: new "Switch between Runs and Pipelines" row.
+
+## Not covered
+- No UI capture or device run (ui-review owns that).
+- The text-field test pins the platform to Android so that Ctrl+A means select all. On Apple platforms Ctrl+A is line start in the field; the field still keeps it, but that case is not tested.
+- The chat composer is not tested directly; it is a text field, so the same guard applies.
+- On web, the browser may keep Ctrl+A; the registry caveat does not mention this.
diff --git a/app/notes/first-run-walkthrough.md b/app/notes/first-run-walkthrough.md
new file mode 100644
index 00000000..679ac1d4
--- /dev/null
+++ b/app/notes/first-run-walkthrough.md
@@ -0,0 +1,117 @@
+# First-run walkthrough
+
+A short, skippable four-page walkthrough for new users of the Flutter app.
+
+## What it does
+
+- Shows once per device on first launch, from the Pipelines page.
+- Is also offered once per server when the device has already seen it and the
+ connected server has no pipelines, runs or chats yet (the server is checked
+ with `list_pipelines`, `list_runs` and `chat_sessions`; an unreadable server
+ never triggers it).
+- Pages: 1) what Pipelines is and how to connect to the server; 2) set up an
+ agent harness, with an agent picker and one copy button for
+ `pipelines harness setup ` (`claude`, `codex`, `opencode`, `pi`);
+ 3) the Pipelines and Runs tabs and how to start a run; 4) the Chat tab, float
+ and terminal.
+- Every page has Skip; Back and Next move between pages; Done ends on the last.
+- Closing by any route (Skip, Done, the close gesture, a tap outside) records the
+ device as seen.
+- Settings reopens it from Tools → Help → "Show the walkthrough". Reopening
+ does not change the seen record.
+
+## Where it lives
+
+- `lib/features/walkthrough/`
+ - `walkthrough_store.dart`: the seen/offered records (`pipelines.next.*` keys;
+ a store that cannot be read reports "seen", so it never nags).
+ - `walkthrough_steps.dart`: the page copy and agent list (pure data).
+ - `first_run_walkthrough.dart`: the stepper and `showFirstRunWalkthrough`
+ (a Material bottom sheet on phones, a dialog on wide windows, via
+ `showAppDetails`).
+ - `walkthrough_harness_command.dart`: agent chips, the command and copy.
+ - `walkthrough_gate.dart`: the first-launch and empty-server check.
+- `lib/application/pipelines_app.dart`: wraps the Pipelines destination body in
+ the gate (the Pipelines tab is the first screen).
+- `lib/features/settings/settings_walkthrough_section.dart`: one row in the
+ Tools → Help group, plus `SettingsKeys.walkthrough`.
+
+## Focused tests
+
+- `test/features/walkthrough/walkthrough_gate_test.dart`: first launch shows
+ once; Done and Skip persist; a seen device on an empty server is offered once;
+ a seen device that starts disconnected makes no server call and is offered
+ after it connects; an unreadable check is retried on the next connection (and
+ a repeated notification while connected does not re-query); a server with
+ work, an unreadable server, a hidden Pipelines page, and an unavailable store
+ all stay quiet; hiding the Pipelines page while the first-launch read is
+ still pending keeps the walkthrough closed, and showing it again offers it
+ once.
+- `test/features/walkthrough/first_run_walkthrough_test.dart`: phone bottom
+ sheet and wide dialog; Back disabled on page 1; four pages with Done on the
+ last and Skip throughout; the harness picker and copy; large text (2x) and
+ dark mode without overflow.
+- `test/features/settings/settings_walkthrough_test.dart`: the Settings row
+ reopens the walkthrough on page 1.
+
+## Results
+
+- Focused run: `tool/memwatch/full.sh 'test/features/walkthrough/first_run_walkthrough_test.dart test/features/walkthrough/walkthrough_gate_test.dart test/features/settings/settings_walkthrough_test.dart'`
+ → PASS, 20 passed, 0 failed, peak 1031 MB, 16 s. The verdict named only these
+ three paths.
+- Visibility fix (review must-fix, visit 2): the gate offered without checking
+ `enabled`, so a walkthrough could open over another destination if Pipelines
+ was hidden before the post-frame callback or during a pending read. The gate
+ now checks `mounted && enabled` in the callback, after each await, and before
+ each show. A skipped callback clears the in-flight flag, so re-enabling
+ Pipelines reschedules the offer. Covered by the new gate test
+ "hiding Pipelines while an offer is pending keeps the walkthrough closed".
+ That test was not run against the pre-fix code, so the failing-before claim
+ is by reasoning only.
+- Lifecycle fix (review must-fix): the empty-server check used to run once
+ right after the first frame, before the session connected. A seen device
+ then got a `NotConnectedError`, and the check was never retried. The gate now
+ takes the session as its connection source (`connection` + `connected`), waits
+ while disconnected, re-runs on each new connection until the server answers,
+ and stays quiet on a repeated notification while connected. A connection that
+ arrives between frames requests a visual update, so the post-frame callback
+ runs. The fix is covered by the two new gate tests above.
+- Two earlier runs failed and were fixed in the test code, not by weakening
+ expectations: the large-text test tapped Next before scrolling it into view,
+ and the "unavailable store" test awaited the real preferences plugin inside
+ `testWidgets` and hung. The store now takes an injectable opener, so that case
+ is a plain test with a null opener.
+- `tool/analyze.sh`: clean (0 errors, 0 warnings, 0 infos).
+- Not run here: `pipelines_app_test`, the Settings screen suites and the other
+ Pipelines suites. They belong to the land gate.
+
+## Affected states (checked by focused tests only; nothing captured)
+
+- Phone (390×844): bottom sheet; page 1 with Back disabled; all four pages;
+ Skip mid-walkthrough.
+- Wide (1280×900): dialog; Next reaches page 2.
+- Harness page: four agent chips; the command follows the selected agent; copy
+ copies the selected command and the button shows a check.
+- Large text (2×) on a 360×740 phone and dark mode: every page builds with no
+ exception.
+- Gate: first launch once; Done and Skip persist; a seen device on an empty
+ server is offered once per server; a server with runs, an unreadable server,
+ a hidden Pipelines page and an unavailable store stay quiet.
+- Settings: "Show the walkthrough" reopens page 1 and does not change the seen
+ record.
+
+Nothing was built, run on a device or captured. `ui-review` owns the rendered
+review.
+
+## Limitations
+
+- The gate is tested in isolation with fake stores and gateways. The Pipelines
+ wiring in `pipelines_app.dart` is not covered by a focused test.
+- Narrow window: the empty-server offer marks the server as offered before it
+ shows. If Pipelines is hidden during that one store write, the server is
+ consumed without the walkthrough appearing. Fixing it needs the store write
+ to move to the dialog's close, which changes when the offer is recorded.
+- On phones the walkthrough is a Material bottom sheet, not a full page.
+- The harness command is shown as a picker with one copy button for the
+ selected agent, not four separate copy buttons.
+- The "Show the walkthrough" test covers the row, not the whole Settings tree.
diff --git a/app/notes/floating-windows.md b/app/notes/floating-windows.md
index f02bd8c5..fe6370be 100644
--- a/app/notes/floating-windows.md
+++ b/app/notes/floating-windows.md
@@ -15,7 +15,8 @@ mode (below). `FloatingLayer`, the overlay the old windows used, is gone.
- `WindowHost`: the windows as plain children of the terminal stage's stack, in
the shell page (not an overlay above it), outside every destination.
- `WindowLayer` / `WindowFrame`: one window's card, title bar (drag, double
- click to maximise, kind actions, Minimise, Maximise, Close) and resize corner.
+ click to maximise, kind actions, Maximise, the X = minimise) and resize corner.
+ There is no separate Minimise button; the X hides the window and keeps it.
- `WindowNavigator`: each window's own page stack.
- `WindowFocus`: a focus scope per window; the keyboard follows the top window
and returns to what had it when the last one hides.
@@ -73,8 +74,8 @@ the device, not a server) and `TerminalWindows`, which keeps it in step with
float, panel height); the bottom panel is still a shell panel.
- Showing the terminal in float mode opens or shows the window; hiding it
- (Alt+T, Ctrl+`, the options menu) minimises it. The window's Minimise and
- Close both hide the terminal. Its shells and tabs live in `TerminalHub`, so
+ (Alt+T, Ctrl+`, the options menu) minimises it. The window's X (minimise)
+ hides the terminal. Its shells and tabs live in `TerminalHub`, so
nothing is lost either way, and the window comes back where it was.
- The frame and maximised state are the window system's. The first window
takes the ones `pipelines.terminal-layout.v1` saved before; that record is
diff --git a/app/notes/navigation-rail.md b/app/notes/navigation-rail.md
new file mode 100644
index 00000000..544302a5
--- /dev/null
+++ b/app/notes/navigation-rail.md
@@ -0,0 +1,124 @@
+# Wide destination rail with Settings
+
+On a wide window the shell's four destinations (Pipelines, Runs, Chat, Search)
+move from the floating bottom-left pill to a Material `NavigationRail` at the
+left edge, with Settings pinned to its foot. The rail keeps the running and
+unread badges. The Pipelines toolbar's Settings gear is removed where the rail
+shows. Phone and narrow layouts are unchanged.
+
+## Design
+
+- **Threshold.** The rail shows at window width >= 697
+ (`kNavigationRailMinWindowWidth` = `kListDetailMinWidth` 600 +
+ `kNavigationRailSpace` 97, the rail plus its divider). The body beside the
+ rail therefore still meets the list/detail split threshold at 697 px. Between
+ 600 and 696 px the floating bar and split layout stay as before.
+- **Layout.** `AdaptiveShell.build` returns the same tree at every width:
+ `Row[rail slot, divider slot, Expanded(ShellRailScope(Scaffold))]`. On a
+ phone the first two slots are empty. Resizing across the threshold does not
+ remount a destination, and pages pushed over a tab keep their state.
+- **Body width.** `ShellRailScope.bodyWidth` is the window width less the rail
+ and its divider (`kNavigationRailSpace` = 97), computed in `build`. The
+ list/detail policy reads it through `ShellRailScope.windowWidth`
+ (`list_detail.dart`, `list_detail_policy.dart`), so `showsListBesideDetail`
+ and the pane widths follow the body. Outside the scope the window width still
+ applies.
+- **Rail items** (`navigation_rail.dart`). Four `NavigationRailDestination`s
+ with `labelType: all`, `trailingAtBottom: true`. Each tab's icon keeps its
+ badge (`_icon`), a `Tooltip` with its label, and the `shell.destination.`
+ key the floating bar used. Settings is a custom `_SettingsRailItem` in
+ `trailing`, styled like a rail destination (stadium indicator, same colours).
+ A `NavigationRailDestination` cannot be pinned, so it is not one.
+- **Window host.** Floating windows overlay the whole app, so `WindowHost` takes
+ `reservesRail` (set by `pipelines_app.dart`) and starts its bounds after the
+ rail and divider (`kNavigationRailSpace`, 97 px, the same inset the shell
+ uses) when the window is wide enough. Tests that mount the host without a
+ shell keep the full width.
+- **Pipelines gear.** `ShellRailScope.isShown` hides `pipelines-open-settings`
+ in the shell's toolbar while the rail shows. On a phone it stays.
+
+## Changed paths
+
+- `app/lib/shell/navigation_rail.dart` (new): rail widget, Settings item,
+ threshold constants.
+- `app/lib/shell/shell_rail_scope.dart` (new): body-width scope.
+- `app/lib/shell/adaptive_shell.dart`: rail layout and constant tree shape.
+- `app/lib/shell/list_detail.dart`, `app/lib/shell/list_detail_policy.dart`:
+ read the body width through the scope.
+- `app/lib/shell/windows/window_host.dart`: `reservesRail` inset (97 px).
+- `app/lib/shell/destination.dart`: comment only.
+- `app/lib/features/pipelines/screen.dart`: gear hidden beside the rail.
+- `app/lib/application/pipelines_app.dart`: `WindowHost(reservesRail: true)`.
+
+## Focused results
+
+Review fix (off-by-one at the threshold): the rail threshold and the
+`WindowHost` inset both use `kNavigationRailSpace` (97). Re-run from `app/`
+with `tool/memwatch/full.sh`:
+
+- Rail and window-host files (`navigation_rail_test`, `windows/window_host_test`,
+ `windows/window_layering_test`): `PASS: 21 passed` earlier, then covered by the
+ run below.
+- All 18 changed test files plus the rail and window-host tests
+ (`application/`, `features/chat/`, `shell/`, `shell/windows/`):
+ `memwatch: PASS: 108 passed, 0 failed, 0 skipped; exit 0`. The verdict names
+ only the intended paths.
+- `tool/analyze.sh` (whole app, run after the focused tests): `analyze: clean`.
+
+New tests (`test/shell/navigation_rail_test.dart`):
+
+- Wide: labelled rail, full height, left edge, Settings pinned below the tabs.
+- Selection marks the tab and one tap selects another.
+- Settings opens as a page from the rail foot; no tab is selected meanwhile;
+ Back returns to Pipelines.
+- Running count on the Runs item of the rail.
+- A list and its open item lay out to the right of the rail.
+- The rail appears at 697 and not at 696; at 697 the list and detail sit side by
+ side (list starts at 97, detail ends at 697); phone and 640 keep the floating bar.
+- Floating windows start after the rail (97) with `reservesRail`, and at 500 px
+ they use the full width.
+- Crossing the threshold keeps a destination mounted with its state.
+
+Updated expectations (each one is a consequence of the rail, not a behaviour
+change the task did not ask for):
+
+- Wide-window floating-bar tests moved to 640 px, where the bar still sits
+ beside the list (`floating_tab_bar_test`, `split_destination_bar_test`,
+ `split_detail_pages_test`, `split_status_bar_test`, `pane_bar_row_test`,
+ `chat_sidebar_clearance_test`). The width-driven policy numbers
+ (`list_pane_resize_test`) now use the body width.
+- `settings_page_test`: the gear case runs on a phone; a wide case opens
+ Settings from the rail. `tab_location_navigation_test` uses the rail's
+ Settings item at 1100 px.
+- `chat_registration_test`, `chat_list_detail_test`, `attention_badge_test`:
+ the rail replaces the bottom bar at wide widths.
+- `list_pane_resize_test` (grip): one `pumpAndSettle` instead of one `pump`.
+ The focus emphasis reaches the grip one frame later beside the rail. The
+ expectation (emphasised on focus) is unchanged.
+- `chat_sidebar_clearance_test`: the scroll offset is kept up to the new
+ maximum extent. At 640 px the list is narrower than beside the rail, so its
+ rows re-wrap and the content is shorter.
+- `chat_split_integration_test`: the compact menu's "Runs" is picked by
+ element, not by text, because the rail also labels Runs. The rail's tooltips
+ keep `byTooltip('Chat')` working.
+- Floating-window expectation (`navigation_rail_test`): the probe window starts at
+ `100 + kNavigationRailSpace` (97), not 96.
+
+## Affected states
+
+- Wide, rail shown (>= 697 px): rail with badges, Settings pinned, lists beside
+ the rail, floating windows beside it, no Pipelines gear, Settings page with
+ Back.
+- 600-696 px: floating bar and split layout as before (no rail).
+- Phone: unchanged, including the Pipelines gear.
+
+## Limitations
+
+- Not verified in a browser or on a device. `ui-review` owns captures. The
+ visual match of the rail and the Settings item is by reading the Material
+ sources, not by a capture.
+- The terminal panel is laid over the app's bottom edge (`TerminalStage`), not
+ inside the shell. When it is open on a wide window it may cover the rail's
+ foot and Settings. This follows from the stack layout; it was not captured.
+- The compact list's "Menu" sheet (`ShellDestinationMenu`) still offers the
+ destinations beside the rail. It is a duplicate, not a removed feature.
diff --git a/app/notes/notification-thread-grouping.md b/app/notes/notification-thread-grouping.md
new file mode 100644
index 00000000..353570bc
--- /dev/null
+++ b/app/notes/notification-thread-grouping.md
@@ -0,0 +1,71 @@
+# Android notifications grouped per chat and run
+
+## What changed (native service only; Flutter unchanged)
+
+- `android/.../notify/NotificationThreads.kt` (new): `ThreadEntry`, `ThreadHistory`
+ (bounded per-thread entries, bounded thread count, persisted through the
+ ledger's `LedgerStore` under `threads.history`), and naming helpers. Threads are
+ keyed by the server `group` (`chat:` or `run:`, per `docs/ntfy.md`).
+- `NotificationPresenter.kt`: a grouped notification posts one conversation
+ notification per thread with a stable id (`thread:`), the latest 5 lines
+ (sender = chat title, run title for runs), the unread count (`setNumber`), and a
+ shared group per namespace (`pipelines.chats`, `pipelines.runs`). The group
+ summary reads "N chats" / "N runs" and is removed when fewer than two are shown.
+ Empty-group notifications keep the old standalone path. Channels and importance
+ are unchanged (`channelFor` takes kind and priority, same rules).
+- `cancel(ids)` removes the cleared entries from history, drops a thread whose
+ entries are all gone, and reposts a partially cleared thread with its new count.
+ `cancelAll()` also clears the history.
+- `NotificationDismissReceiver.kt`: `EXTRA_NOTIFICATION_ID` may carry several
+ newline-separated ids, so a tap or swipe on a thread clears every entry it shows.
+- `NotificationService.kt`, the ledger and the protocol are untouched, so run 405's
+ reconnect/wakelock work is not affected.
+
+## Review fix (visit 2)
+
+- The thread notification now uses `androidx.core.app.NotificationCompat.MessagingStyle`
+ with `androidx.core.app.Person`, built by `NotificationCompat.Builder` (the presenter's
+ builder is compat throughout). Platform `Notification.MessagingStyle` and its API 28
+ BigTextStyle fallback are gone; the compat style renders on every supported API level.
+- `app/android/app/build.gradle.kts` adds `implementation("androidx.core:core:1.15.0")`
+ (already in the offline Gradle cache).
+
+## Focused results
+
+- Gradle 9.1.0 (cached), `--offline`, JDK 17 (`/opt/homebrew/opt/openjdk@17`):
+ `:app:testDebugUnitTest --tests 'net.awan.pipelines_app.notify.*'` → BUILD SUCCESSFUL.
+ JUnit XML: ThreadHistoryTest 9 tests / 0 failures, DeliveryLedgerTest 8 / 0,
+ NotificationProtocolTest 12 / 0.
+- `tool/analyze.sh` (run from `app/`, after the Kotlin tests): clean, exit 0.
+- No Flutter test was run: no Dart source changed.
+- JDK 27 fails the Android JDK image transform (`jlink`) in a plugin, so builds here
+ need JDK 17 (environment issue, unrelated to this change).
+
+## Affected states
+
+- No Flutter UI changed. Native states not exercised on a device: a second chat
+ appearing as a thread, a summary at 2 and 1 chats, tap/swipe on a multi-line
+ thread, and the restart rebuild from persisted history.
+
+## Merge with main (land re-entry)
+
+- main moved `NotificationPresenter.kt` (sign-in notice, `openApp()` helper,
+ `SIGN_IN_ID`, `ACCOUNT_CHANNEL`). Resolved by keeping both sides: the
+ connection notification uses `openApp()`, and the sign-in block, constants and
+ thread code all remain. The merge is staged with `--no-commit`; land concludes it.
+- Gradle, JDK 17, offline: `:app:compileDebugUnitTestKotlin` succeeds.
+- Gradle, JDK 17, offline: `:app:testDebugUnitTest --tests 'net.awan.pipelines_app.notify.*'`
+ passes 37 of 37 (ConnectionLog 5, DeliveryLedger 8, NotificationProtocol 12,
+ ReconnectPolicy 3, ThreadHistory 9).
+- No Dart changed in this stage, so no Flutter tests or analyze were run.
+
+## Limitations
+
+- Android posting (MessagingStyle, summary, PendingIntent extras) is not covered by
+ JVM tests and has not been run on a device. Mobile behaviour is unverified.
+- The new androidx.core dependency is compiled offline but not run through a full
+ APK build or on a device in this stage.
+- History is capped: 100 unread entries per thread (count is capped there) and 50
+ threads; the oldest thread is forgotten first when the cap is hit.
+- Swipe-dismissal of a thread clears its ids on the server, but the local history
+ is trimmed only when the server confirms (`notifications_cleared`).
diff --git a/app/notes/run-detail-output-expanded.md b/app/notes/run-detail-output-expanded.md
new file mode 100644
index 00000000..aa1806ca
--- /dev/null
+++ b/app/notes/run-detail-output-expanded.md
@@ -0,0 +1,39 @@
+# Run detail: Output section starts expanded
+
+## Change
+- The run Summary's Output section (`run-detail-summary-output`) now starts open.
+ Input still starts closed. The Summary's default is restored on a different run
+ and when a search hit names no section (`RunDetailTabs._resetSummarySections`).
+- A visit's Summary Output (`run-visit-section-Output`) starts open; Input starts
+ closed (`_VisitSummaryState._closed = {'Input'}`).
+- Both stay collapsible by tapping the title. The open/closed state lives in the
+ controller or State for that view only; it is not persisted.
+- Long outputs: Output is a sliver. `RunFieldSliver` (in `run_field_body.dart`)
+ builds one `SliverList` row per recorded
+ field, so a map with hundreds of fields lays out only the rows on screen. It
+ is used for the run Summary Output (`_StickyField.sliverBody`) and the visit
+ Summary Output (`_section(..., lazy: true)`), both through `StickySection`'s
+ sliver path. A closed `SliverReveal` builds nothing.
+- Input stays on the box path (`RunFieldBody`); it starts closed, so its cost is
+ paid only when the operator opens it. The box and sliver forms share the row
+ builder, so they render the same fields.
+
+## Tests (run through `tool/memwatch/full.sh`, one quoted path list)
+- Command: `tool/memwatch/full.sh 'test/features/runs/ui/run_detail_visit_sections_test.dart test/features/runs/ui/run_detail_summary_fields_test.dart test/features/runs/ui/run_detail_widget_test.dart test/features/runs/ui/run_search_selection_test.dart test/features/runs/ui/run_detail_tabs_test.dart test/features/runs/ui/run_detail_visit_test.dart'`
+- Verdict (final code): `PASS: 49 passed, 0 failed, 0 skipped; peak 1884 MB; 32s; exit 0`
+- New: visit Output starts expanded and collapses/reopens; run Output starts
+ expanded and collapses for the view; a 500-field visit Output opens with only
+ its first field built and the page scrolls to the last one (lazy regression).
+- Updated (the old expectation was that Output started closed): visit tab/empty-state
+ tests, run Summary empty-wording and recorded-input tests, search-selection tests
+ for input, retired field and replacing a visit with the Summary.
+- Not changed: Input's closed default and every Input expectation.
+
+## Analyze
+- `tool/analyze.sh`: `analyze: clean; 10s; exit 0`
+- `dart format --set-exit-if-changed` on the changed files: formatted one widget
+ test file (whitespace only).
+
+## Limitations
+- No widget capture or browser/device check was run here; ui-review owns that.
+- Very long Output is laid out when the section opens. Not measured for jank.
diff --git a/app/notes/window-x-minimises.md b/app/notes/window-x-minimises.md
new file mode 100644
index 00000000..d933b110
--- /dev/null
+++ b/app/notes/window-x-minimises.md
@@ -0,0 +1,55 @@
+# Window X minimises (no separate Minimise button)
+
+## Change
+
+- The title bar of a floating window is now: kind actions (Dock on a chat),
+ Maximise / Restore size, then the X.
+- The X hides the window and keeps its state, exactly as Minimise did. Its
+ tooltip and semantics are `Minimise`. It keeps the X glyph (`Icons.close`).
+- The X never calls the kind's `closed` hook, so a chat window keeps its chat
+ open on the server and returns nothing to the tiling.
+- `WindowFrame` no longer takes `onClose`; `WindowLayer` wires the X to
+ `manager.setMinimized(id, true)`.
+- Unchanged: the chord (Alt+Y) shows hidden chat windows; the Windows menu
+ still lists minimised windows with a minimise mark and shows them on choice;
+ Show all, Minimise all and Close all stay in that menu. Terminal windows
+ still hide the terminal when their window is hidden by the X.
+
+Changed paths (under `app/`):
+
+- `lib/shell/windows/window_frame.dart`, `window_layer.dart`, `window_kind.dart`,
+ `window_entry.dart` (comments and the frame's parameters)
+- `lib/features/terminal/terminal_window.dart` (comment only)
+- `test/shell/windows/window_host_test.dart`, `window_layering_test.dart`
+- `test/features/chat/chat_floating_pane_test.dart`
+- `test/features/terminal/terminal_surface_test.dart`
+- `notes/floating-windows.md`, `notes/chat-floating-pane.md`
+
+## Focused results
+
+- `tool/memwatch/full.sh 'test/shell/windows/window_host_test.dart
+ test/shell/windows/window_layering_test.dart
+ test/shell/windows/window_conveniences_test.dart
+ test/features/chat/chat_floating_pane_test.dart
+ test/features/terminal/terminal_surface_test.dart'`:
+ PASS, 72 passed, 0 failed, 0 skipped, exit 0.
+- `tool/analyze.sh`: clean, exit 0.
+- Not run: the full suite (the land gate runs it). No Cupertino code or tests
+ touched.
+
+## Affected states (widget-test coverage only)
+
+- Window title bar: no `Close` tooltip; `Minimise` on the X; `Maximise` /
+ `Restore size` unchanged.
+- Chat window: X hides it; the chat stays open, is not docked and sends no
+ `chat_close`; the chord shows it again with the same frame and composer.
+- Probe window: X keeps the entry (minimised), the content state survives, and
+ the group toggle brings it back.
+- Terminal float window: X hides the terminal and keeps its tabs; the chord
+ shows it again at the same frame.
+
+## Limitations
+
+- No browser or device capture here; `ui-review` owns the title-bar captures.
+- The X glyph with a Minimise tooltip is a deliberate choice; a minimise glyph
+ would be a one-line change in `window_frame.dart` if preferred.
diff --git a/app/test/application/app_terminals_test.dart b/app/test/application/app_terminals_test.dart
new file mode 100644
index 00000000..6a079cee
--- /dev/null
+++ b/app/test/application/app_terminals_test.dart
@@ -0,0 +1,65 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/application/app_terminals.dart';
+import 'package:pipelines_app/features/terminal/terminal_layout.dart';
+import 'package:pipelines_app/features/terminal/terminal_toggle_button.dart';
+
+import '../features/terminal/terminal_fixtures.dart';
+
+void main() {
+ late TerminalGateway gateway;
+ late AppTerminals terminals;
+
+ setUp(() {
+ gateway = TerminalGateway();
+ terminals = AppTerminals(
+ pool: null,
+ connection: ValueNotifier(0),
+ connected: () => true,
+ gateway: gateway,
+ machineId: 'mac',
+ machineName: 'Mac',
+ layout: TerminalLayout(store: MemoryLayoutStore()),
+ );
+ });
+
+ tearDown(() {
+ terminals.dispose();
+ gateway.close();
+ });
+
+ /// Pumps [AppTerminals.barToggle] at [width] and returns what it built.
+ Future barToggleAt(WidgetTester tester, double width) async {
+ Widget? built;
+ await tester.pumpWidget(
+ MaterialApp(
+ home: MediaQuery(
+ data: MediaQueryData(size: Size(width, 800)),
+ child: Builder(
+ builder: (context) {
+ built = terminals.barToggle(context);
+ return const SizedBox.shrink();
+ },
+ ),
+ ),
+ ),
+ );
+ return built;
+ }
+
+ testWidgets('the Chat shell bar offers the terminal toggle on a wide layout', (
+ tester,
+ ) async {
+ final built = await barToggleAt(tester, 1000);
+ expect(built, isA());
+ });
+
+ testWidgets('a narrow layout has no terminal toggle in the shell bar', (
+ tester,
+ ) async {
+ // Covers both a narrow chat list and an open narrow chat: the open chat's
+ // own bar carries the terminal (terminal_chat_bar_action_test.dart).
+ final built = await barToggleAt(tester, 390);
+ expect(built, isNull);
+ });
+}
diff --git a/app/test/application/chat_registration_test.dart b/app/test/application/chat_registration_test.dart
index da69f33a..ece89f0e 100644
--- a/app/test/application/chat_registration_test.dart
+++ b/app/test/application/chat_registration_test.dart
@@ -285,12 +285,12 @@ void main() {
expect(find.byKey(const Key('chat-turn-activity')), findsOneWidget);
expect(find.text('Kept behind a native disclosure.'), findsNothing);
- // The shell bar stays over the list and tabs; the open chat draws its
- // own floating bar in its pane, with no Back: the list beside it is the
- // way out.
+ // The destination rail sits at the left edge; the shell bar stays over
+ // the list, and the open chat draws its own floating bar in its pane,
+ // with no Back: the list beside it is the way out.
expect(find.byType(ChatSessionsScreen), findsOneWidget);
- expect(find.byType(NavigationRail), findsNothing);
- expect(find.byType(FloatingDestinationBar), findsOneWidget);
+ expect(find.byType(NavigationRail), findsOneWidget);
+ expect(find.byType(FloatingDestinationBar), findsNothing);
// The shell's bar and the conversation's own header.
expect(find.byType(SegmentedBar), findsNWidgets(2));
expect(find.byType(AppBar), findsNothing);
diff --git a/app/test/application/settings_page_test.dart b/app/test/application/settings_page_test.dart
index 73606176..e27df3ca 100644
--- a/app/test/application/settings_page_test.dart
+++ b/app/test/application/settings_page_test.dart
@@ -13,9 +13,9 @@ import '../features/pipelines/fixtures.dart';
import 'pipelines_app_test.dart' show webServer;
import 'pipelines_replies.dart';
-/// Settings is not a tab: it opens as a page from the gear in the Pipelines
-/// bar, keeps its `/settings` route (and deep link), and closes back to
-/// Pipelines. The tab bar keeps Pipelines selected meanwhile.
+/// Settings is not a tab: it opens as a page (from the gear in the Pipelines
+/// bar on a phone, from the rail's foot on a wide window), keeps its
+/// `/settings` route (and deep link), and closes back to Pipelines. The tab bar keeps Pipelines selected meanwhile.
void main() {
Future pumpApp(
WidgetTester tester, {
@@ -50,7 +50,9 @@ void main() {
.widget(find.byType(FloatingDestinationBar))
.currentIndex;
- for (final size in [const Size(390, 844), const Size(1200, 800)]) {
+ // A phone's Pipelines bar keeps the gear; a wide window's rail offers
+ // Settings instead (see the wide test below).
+ for (final size in [const Size(390, 844)]) {
testWidgets('${size.width}: the Pipelines bar gear opens Settings '
'as a page and Back returns', (tester) async {
final provider = await pumpApp(
@@ -101,6 +103,57 @@ void main() {
});
}
+ testWidgets('1200: the rail offers Settings at its foot and no gear is '
+ 'left in the Pipelines toolbar; Settings is a page and Back returns', (
+ tester,
+ ) async {
+ final provider = await pumpApp(
+ tester,
+ location: '/pipelines',
+ size: const Size(1200, 800),
+ );
+ expect(find.byType(NavigationRail), findsOneWidget);
+ expect(find.byKey(const Key('pipelines-open-settings')), findsNothing);
+ expect(find.byType(FloatingDestinationBar), findsNothing);
+ final rail = tester.widget(find.byType(NavigationRail));
+ expect(rail.selectedIndex, 0);
+ for (final label in ['Pipelines', 'Runs', 'Chat', 'Search', 'Settings']) {
+ expect(
+ find.descendant(
+ of: find.byType(NavigationRail),
+ matching: find.text(label),
+ ),
+ findsOneWidget,
+ reason: label,
+ );
+ }
+
+ await tester.tap(find.byKey(const ValueKey('shell.destination.settings')));
+ await tester.pump();
+ await tester.pump();
+ expect(provider.value.uri.path, '/settings');
+ expect(find.byType(SettingsScreen), findsOneWidget);
+ // Settings is a page of Pipelines: the rail marks Settings, not a tab.
+ expect(
+ tester.widget(find.byType(NavigationRail)).selectedIndex,
+ isNull,
+ );
+ expect(find.byKey(const ValueKey('shell.back')), findsOneWidget);
+ expect(tester.takeException(), isNull);
+
+ await tester.tap(find.byKey(const ValueKey('shell.back')));
+ await tester.pump();
+ await tester.pump();
+ expect(provider.value.uri.path, '/pipelines');
+ expect(find.byKey(const Key('pipelines-open-settings')), findsNothing);
+ expect(
+ tester.widget(find.byType(NavigationRail)).selectedIndex,
+ 0,
+ );
+ await tester.pumpWidget(const SizedBox.shrink());
+ await tester.pump();
+ });
+
testWidgets('the /settings deep link opens the Settings page and '
'the system Back closes it to Pipelines', (tester) async {
final provider = await pumpApp(
diff --git a/app/test/application/tab_location_navigation_test.dart b/app/test/application/tab_location_navigation_test.dart
index 1197cd27..55de9dbf 100644
--- a/app/test/application/tab_location_navigation_test.dart
+++ b/app/test/application/tab_location_navigation_test.dart
@@ -179,11 +179,9 @@ void main() {
final before = tester.widget(find.byType(PipelinesScreen));
expect(before.initialPipelineId, 1);
final pipelineState = tester.state(find.byType(PipelinesScreen));
- await tapBarAction(
- tester,
- find.byKey(const Key('pipelines-open-settings')),
- 'Settings',
- );
+ // Wide: the rail offers Settings (the toolbar gear is gone).
+ expect(find.byKey(const Key('pipelines-open-settings')), findsNothing);
+ await tester.tap(find.byKey(const ValueKey('shell.destination.settings')));
await tester.pumpAndSettle();
expect(app.provider.value.uri.path, '/settings');
final hidden = find.byType(PipelinesScreen, skipOffstage: false);
diff --git a/app/test/features/chat/chat_control_tab_test.dart b/app/test/features/chat/chat_control_tab_test.dart
index 06c68556..2c110416 100644
--- a/app/test/features/chat/chat_control_tab_test.dart
+++ b/app/test/features/chat/chat_control_tab_test.dart
@@ -133,9 +133,8 @@ void main() {
await tester.pumpWidget(const SizedBox.shrink());
});
- testWidgets('single pane focuses input; empty workspace does not consume', (
- tester,
- ) async {
+ testWidgets('single pane with no shown window does nothing; empty workspace '
+ 'does not consume', (tester) async {
await _setup(tester, open: false);
await _chord(tester);
expect(find.byType(ChatWorkspace), findsNothing);
@@ -144,7 +143,9 @@ void main() {
_focusSidebar(tester);
await tester.pumpAndSettle();
await _chord(tester);
- expect(_editable(tester, 'a').focusNode.hasPrimaryFocus, isTrue);
+ expect(find.byType(ChatWorkspace), findsOneWidget);
+ expect(_workspace(tester).paneCount, 1);
+ expect(_editable(tester, 'a').focusNode.hasPrimaryFocus, isFalse);
expect(_editable(tester, 'a').controller.text, isEmpty);
await tester.pumpWidget(const SizedBox.shrink());
});
diff --git a/app/test/features/chat/chat_floating_pane_test.dart b/app/test/features/chat/chat_floating_pane_test.dart
index ceb1a11e..818f0cca 100644
--- a/app/test/features/chat/chat_floating_pane_test.dart
+++ b/app/test/features/chat/chat_floating_pane_test.dart
@@ -390,19 +390,24 @@ void main() {
await app.stop(tester);
});
- testWidgets('X closes the window and returns nothing to the tiling', (
- tester,
- ) async {
+ testWidgets('X minimises the window: the chat stays open, returns nothing '
+ 'to the tiling, and the chord brings the window back', (tester) async {
await _saved('a', 'b');
final app = _App(_Store());
await app.start(tester);
await _menu(tester, 'b', 'Float (Alt+Y)');
- await tester.tap(find.byTooltip('Close'));
+ await tester.tap(find.byTooltip('Minimise'));
await tester.pumpAndSettle();
- expect(app.floating, isEmpty);
+ // Still a window, hidden; not closed and not docked.
+ expect(app.floating, ['b']);
+ expect(app.windows.windows.single.minimized, isTrue);
+ expect(_shown('Chat b'), findsNothing);
expect(_workspace(tester).panes.map((p) => p.sessionId), ['a']);
- expect(_thread('b'), findsNothing);
expect(app.gateway.calls.where((c) => c.type == 'chat_close'), isEmpty);
+ await _chord(tester);
+ expect(_shown('Chat b'), findsOneWidget);
+ expect(_thread('b').hitTestable(), findsOneWidget);
+ expect(app.floating, ['b']);
await app.stop(tester);
});
@@ -526,25 +531,36 @@ void main() {
await tester.pumpAndSettle();
expect(app.floating, ['b', 'c', 'a']);
+ // The cycle follows the order the windows were opened in (b, c, a), not
+ // the stacking order, which each raise changes. From a (opened last) the
+ // next is b, the first opened.
await _tab(tester);
expect(app.floating, ['c', 'a', 'b']);
expect(_composerFocused(tester, 'b'), isTrue);
- // Past the top, the bottom window comes up again.
await _tab(tester);
expect(app.floating, ['a', 'b', 'c']);
expect(_composerFocused(tester, 'c'), isTrue);
+ await _tab(tester);
+ expect(app.floating, ['b', 'c', 'a']);
+ expect(_composerFocused(tester, 'a'), isTrue);
+ await _tab(tester, shift: true);
+ expect(app.floating, ['b', 'a', 'c']);
+ expect(_composerFocused(tester, 'c'), isTrue);
await _tab(tester, shift: true);
expect(app.floating, ['a', 'c', 'b']);
expect(_composerFocused(tester, 'b'), isTrue);
+ // Back past the first opened: the last opened (a) comes up.
await _tab(tester, shift: true);
- expect(app.floating, ['a', 'b', 'c']);
- expect(_composerFocused(tester, 'c'), isTrue);
+ expect(app.floating, ['c', 'b', 'a']);
+ expect(_composerFocused(tester, 'a'), isTrue);
expect(tester.takeException(), isNull);
await app.stop(tester);
});
- testWidgets('with the tiling focused Ctrl+Tab cycles its panes and leaves '
- 'the windows alone', (tester) async {
+ testWidgets('with the tiling focused Ctrl+Tab goes to the top-most shown '
+ 'window, and cycles the panes only when no window is shown', (
+ tester,
+ ) async {
await _saved('a', 'b', 'c');
final app = _App(_Store());
await app.start(tester);
@@ -552,26 +568,61 @@ void main() {
expect(app.floating, ['c']);
final controller = _workspace(tester);
+ // A window is shown: from the tiling, Ctrl+Tab takes the keyboard to it
+ // and the panes stay where they are.
await tester.tapAt(tester.getCenter(_input('a')));
await tester.pump();
expect(controller.activePane?.sessionId, 'a');
await _tab(tester);
- expect(controller.activePane?.sessionId, 'b');
- expect(_composerFocused(tester, 'b'), isTrue);
+ expect(controller.activePane?.sessionId, 'a');
+ expect(_composerFocused(tester, 'c'), isTrue);
expect(app.floating, ['c']);
- // With a window focused, the panes stay where they are; a single window
- // has nothing to cycle to.
- await tester.tapAt(tester.getCenter(_input('c')));
- await tester.pump();
+ // A single shown window has nothing to cycle to.
+ await _tab(tester);
+ expect(controller.activePane?.sessionId, 'a');
expect(_composerFocused(tester, 'c'), isTrue);
+ expect(app.floating, ['c']);
+
+ // No window shown: the panes cycle and the hidden window stays hidden.
+ await _chord(tester);
+ expect(_shown('Chat c'), findsNothing);
+ await tester.tapAt(tester.getCenter(_input('a')));
+ await tester.pump();
await _tab(tester);
expect(controller.activePane?.sessionId, 'b');
+ expect(_composerFocused(tester, 'b'), isTrue);
+ expect(_shown('Chat c'), findsNothing);
expect(app.floating, ['c']);
expect(tester.takeException(), isNull);
await app.stop(tester);
});
+ testWidgets('with one tiled pane and no shown window Ctrl+Tab does nothing; '
+ 'a minimised chat is not brought up', (tester) async {
+ await _saved('a', 'b');
+ final app = _App(_Store());
+ await app.start(tester);
+ await _menu(tester, 'b', 'Float (Alt+Y)');
+ await tester.tap(find.byTooltip('Minimise'));
+ await tester.pumpAndSettle();
+ expect(_shown('Chat b'), findsNothing);
+ final controller = _workspace(tester);
+ expect(controller.panes.map((p) => p.sessionId), ['a']);
+
+ await tester.tapAt(tester.getCenter(_input('a')));
+ await tester.pump();
+ await _tab(tester);
+ await _tab(tester, shift: true);
+ expect(controller.panes.map((p) => p.sessionId), ['a']);
+ expect(controller.activePane?.sessionId, 'a');
+ expect(_shown('Chat b'), findsNothing);
+ expect(app.floating, ['b']);
+ expect(app.opened, isEmpty);
+ expect(tester.takeException(), isNull);
+ await app.stop(tester);
+ });
+
testWidgets('a terminal that claims tab keys keeps Ctrl+Tab over a focused '
'floating chat', (tester) async {
await _saved('a', 'b', 'c');
diff --git a/app/test/features/chat/chat_keyboard_focus_test.dart b/app/test/features/chat/chat_keyboard_focus_test.dart
index ce38721e..653f42d5 100644
--- a/app/test/features/chat/chat_keyboard_focus_test.dart
+++ b/app/test/features/chat/chat_keyboard_focus_test.dart
@@ -150,38 +150,29 @@ void main() {
await tester.pumpWidget(const SizedBox.shrink());
});
- testWidgets('Control Tab over one pane returns to the previous chat', (
- tester,
- ) async {
+ testWidgets('Control Tab over one pane does nothing: it never brings up '
+ 'another chat', (tester) async {
await _setup(tester);
await _openRow(tester, 'a');
final workspace = _workspace(tester);
- // Nothing shown before: the chord only focuses the composer.
await _controlTab(tester);
expect(workspace.activePane?.sessionId, 'a');
- expect(_editable(tester, 'a').focusNode.hasPrimaryFocus, isTrue);
+ expect(_editable(tester, 'a').focusNode.hasPrimaryFocus, isFalse);
+ // Opening b replaces the lone pane; a is no longer shown anywhere.
await _openRow(tester, 'b');
await tester.enterText(_input('b'), 'Draft B');
await _focusSidebar(tester);
- for (final id in ['a', 'b', 'a']) {
- await _controlTab(tester);
+ for (final shift in [false, true]) {
+ await _controlTab(tester, shift: shift);
expect(workspace.paneCount, 1);
- expect(workspace.activePane?.sessionId, id);
- expect(_editable(tester, id).focusNode.hasPrimaryFocus, isTrue);
+ expect(workspace.activePane?.sessionId, 'b');
+ expect(_editable(tester, 'b').focusNode.hasPrimaryFocus, isFalse);
+ expect(_editable(tester, 'b').controller.text, 'Draft B');
}
- await _controlTab(tester, shift: true);
- expect(workspace.activePane?.sessionId, 'b');
- expect(_editable(tester, 'b').controller.text, 'Draft B');
- // A third chat makes the pair c and b; a is no longer one step away.
+ // Two panes cycle the panes, not the history.
await _openRow(tester, 'c');
- await _controlTab(tester);
- expect(workspace.activePane?.sessionId, 'b');
- await _controlTab(tester);
- expect(workspace.activePane?.sessionId, 'c');
-
- // Two panes cycle the panes as before, not the history.
await tester.tap(_actions('a'));
await tester.pumpAndSettle();
await tester.tap(find.text('Open to the right'));
diff --git a/app/test/features/chat/chat_list_detail_test.dart b/app/test/features/chat/chat_list_detail_test.dart
index 9e3703b3..a96c93ee 100644
--- a/app/test/features/chat/chat_list_detail_test.dart
+++ b/app/test/features/chat/chat_list_detail_test.dart
@@ -50,7 +50,7 @@ Future _pumpShell(WidgetTester tester, Size size) async {
void main() {
for (final size in [const Size(1280, 800), const Size(800, 830)]) {
- testWidgets('a wide window keeps the tab bar and list beside the open chat '
+ testWidgets('a wide window keeps the rail and list beside the open chat '
'at $size', (tester) async {
await _pumpShell(tester, size);
expect(
@@ -68,8 +68,10 @@ void main() {
find.byType(Navigator).first,
);
expect(navigator.canPop(), isFalse, reason: 'No page covers the shell');
- expect(find.byType(NavigationRail), findsNothing);
- expect(find.byType(FloatingDestinationBar), findsOneWidget);
+ // Both sizes are wide enough for the rail (the shell's own bar and list
+ // beside the open chat sit to its right).
+ expect(find.byType(NavigationRail), findsOneWidget);
+ expect(find.byType(FloatingDestinationBar), findsNothing);
expect(find.byKey(const ValueKey('chat-thread-a')), findsOneWidget);
expect(find.text('Second chat'), findsOneWidget);
expect(
diff --git a/app/test/features/chat/chat_sidebar_clearance_test.dart b/app/test/features/chat/chat_sidebar_clearance_test.dart
index 2ed3b3be..c9f9c624 100644
--- a/app/test/features/chat/chat_sidebar_clearance_test.dart
+++ b/app/test/features/chat/chat_sidebar_clearance_test.dart
@@ -11,7 +11,7 @@ void main() {
testWidgets('chat list stays above labeled navigation ($scale)', (
tester,
) async {
- tester.view.physicalSize = const Size(1200, 900);
+ tester.view.physicalSize = const Size(640, 900);
tester.view.devicePixelRatio = 1;
tester.platformDispatcher.textScaleFactorTestValue = scale;
addTearDown(tester.view.reset);
@@ -87,7 +87,13 @@ void main() {
),
same(scrollable),
);
- expect(scrollable.position.pixels, closeTo(retainedOffset, .5));
+ // The list is narrower at 640 (no rail) than beside the rail, so its
+ // rows re-wrap into a shorter scroll extent: the offset is kept up to
+ // that extent, and no further.
+ final kept = retainedOffset < scrollable.position.maxScrollExtent
+ ? retainedOffset
+ : scrollable.position.maxScrollExtent;
+ expect(scrollable.position.pixels, closeTo(kept, .5));
expect(tester.takeException(), isNull);
});
}
diff --git a/app/test/features/chat/chat_split_integration_test.dart b/app/test/features/chat/chat_split_integration_test.dart
index 4d3eb558..c10ea315 100644
--- a/app/test/features/chat/chat_split_integration_test.dart
+++ b/app/test/features/chat/chat_split_integration_test.dart
@@ -106,7 +106,16 @@ void main() {
expect(find.text('Menu'), findsOneWidget);
await tester.tap(find.text('Menu'));
await tester.pumpAndSettle();
- await tester.tap(find.text('Runs'));
+ // The menu's own row: the rail labels Runs too, so take the text that
+ // is not in the rail.
+ await tester.tap(
+ find.byElementPredicate(
+ (element) =>
+ element.widget is Text &&
+ (element.widget as Text).data == 'Runs' &&
+ element.findAncestorWidgetOfExactType() == null,
+ ),
+ );
await tester.pumpAndSettle();
expect(find.text('Runs destination'), findsOneWidget);
await tester.tap(find.byTooltip('Chat'));
diff --git a/app/test/features/notification_service/fake_notification_service.dart b/app/test/features/notification_service/fake_notification_service.dart
index 050be179..511df52f 100644
--- a/app/test/features/notification_service/fake_notification_service.dart
+++ b/app/test/features/notification_service/fake_notification_service.dart
@@ -16,6 +16,7 @@ class FakeNotificationService implements NotificationServiceBridge {
);
NotificationServiceStatus current;
+ List events = const [];
final calls = <(String, Map)>[];
final _changes = StreamController.broadcast();
bool batteryGranted = true;
@@ -85,4 +86,9 @@ class FakeNotificationService implements NotificationServiceBridge {
if (batteryGranted) current = copy(batteryExempt: true);
return true;
}
+
+ // Not recorded in [calls]: the log is re-read after every action, and the
+ // tests assert on the action calls themselves.
+ @override
+ Future> connectionEvents() async => events;
}
diff --git a/app/test/features/notification_service/notification_service_bridge_test.dart b/app/test/features/notification_service/notification_service_bridge_test.dart
index da9fe55f..4c6b0365 100644
--- a/app/test/features/notification_service/notification_service_bridge_test.dart
+++ b/app/test/features/notification_service/notification_service_bridge_test.dart
@@ -92,5 +92,39 @@ void main() {
final bridge = createNotificationServiceBridge();
expect(bridge.supported, isFalse);
expect((await bridge.status()).state, DeliveryState.off);
+ expect(await bridge.connectionEvents(), isEmpty);
+ });
+
+ test('a refused session reports sign_in_required', () {
+ expect(
+ NotificationServiceStatus.fromMap({'status': 'sign_in_required'}).state,
+ DeliveryState.signInRequired,
+ );
+ });
+
+ test('connectionEvents reads the service log, newest first', () async {
+ messenger.setMockMethodCallHandler(channel, (call) async {
+ if (call.method == 'connectionEvents') {
+ return [
+ {
+ 'time': 2000,
+ 'event': 'failed',
+ 'error': 'Expected HTTP 101',
+ 'code': 403,
+ },
+ {'time': 1000, 'event': 'connected'},
+ ];
+ }
+ return reply();
+ });
+ final bridge = MethodChannelNotificationServiceBridge(channel);
+ final events = await bridge.connectionEvents();
+ expect(events.map((event) => event.event), ['failed', 'connected']);
+ expect(events.first.code, 403);
+ expect(events.first.error, 'Expected HTTP 101');
+ expect(events.first.detail, 'HTTP 403 · Expected HTTP 101');
+ expect(events.last.code, isNull);
+ expect(events.last.error, isNull);
+ expect(events.last.time, DateTime.fromMillisecondsSinceEpoch(1000));
});
}
diff --git a/app/test/features/runs/ui/run_detail_summary_fields_test.dart b/app/test/features/runs/ui/run_detail_summary_fields_test.dart
index 019607b6..b156bfc6 100644
--- a/app/test/features/runs/ui/run_detail_summary_fields_test.dart
+++ b/app/test/features/runs/ui/run_detail_summary_fields_test.dart
@@ -244,10 +244,9 @@ void main() {
await tester.pumpAndSettle();
expect(find.text('No input recorded.'), findsOneWidget);
+ // Output starts open, so its empty sentence shows without a tap.
await tester.ensureVisible(find.text('Output'));
await tester.pumpAndSettle();
- await tester.tap(find.text('Output'));
- await tester.pumpAndSettle();
expect(find.text('No output recorded.'), findsOneWidget);
});
@@ -266,5 +265,35 @@ void main() {
await tester.pumpAndSettle();
expect(find.text('ship it'), findsOneWidget);
});
+
+ testWidgets('${platform.name} summary output starts expanded and '
+ 'collapses for this view', (tester) async {
+ await pumpRunDetail(
+ tester,
+ platform,
+ run: recordedRunFixture(),
+ size: const Size(900, 1600),
+ );
+
+ final output = find.byKey(const ValueKey('run-detail-summary-output'));
+ final outputTitle = find.descendant(
+ of: output,
+ matching: find.text('Output'),
+ );
+ final outputBody = find.descendant(of: output, matching: find.text('ok'));
+ // Output opens with its recorded value; Input stays closed.
+ expect(outputBody, findsOneWidget);
+ expect(find.text('ship it'), findsNothing);
+
+ await tester.ensureVisible(outputTitle.first);
+ await tester.pumpAndSettle();
+ await tester.tap(outputTitle.first);
+ await tester.pumpAndSettle();
+ expect(outputBody, findsNothing);
+
+ await tester.tap(outputTitle.first);
+ await tester.pumpAndSettle();
+ expect(outputBody, findsOneWidget);
+ });
}
}
diff --git a/app/test/features/runs/ui/run_detail_visit_sections_test.dart b/app/test/features/runs/ui/run_detail_visit_sections_test.dart
index 9baebc24..c7c13adb 100644
--- a/app/test/features/runs/ui/run_detail_visit_sections_test.dart
+++ b/app/test/features/runs/ui/run_detail_visit_sections_test.dart
@@ -49,21 +49,77 @@ void main() {
}
});
+ testWidgets('${platform.name} visit Output starts expanded and collapses', (
+ tester,
+ ) async {
+ await openVisit(tester, platform);
+ final output = find.byKey(const ValueKey('run-visit-section-Output'));
+ final outputTitle = find.descendant(
+ of: output,
+ matching: find.text('Output'),
+ );
+ final outputBody = find.descendant(of: output, matching: find.text('ok'));
+ final input = find.byKey(const ValueKey('run-visit-section-Input'));
+
+ // Output opens expanded; Input stays closed.
+ expect(find.text('result'), findsOneWidget);
+ expect(outputBody, findsOneWidget);
+ expect(find.text('Ship it.'), findsNothing);
+
+ // The operator can collapse Output, and open it again.
+ await tester.ensureVisible(outputTitle.first);
+ await tester.tap(outputTitle.first);
+ await tester.pumpAndSettle();
+ expect(outputBody, findsNothing);
+ expect(find.text('result'), findsNothing);
+ await tester.tap(outputTitle.first);
+ await tester.pumpAndSettle();
+ expect(outputBody, findsOneWidget);
+ expect(input, findsOneWidget);
+ });
+
+ testWidgets('${platform.name} long visit Output opens lazily and still '
+ 'scrolls to its last field', (tester) async {
+ final run = visitRunFixture();
+ firstVisitStep(run)['output'] = {
+ for (var i = 0; i < 500; i++) 'field$i': 'value $i',
+ };
+ await openVisit(tester, platform, run: run);
+
+ // Open by default, yet only the fields on screen are built.
+ expect(find.text('value 0'), findsOneWidget);
+ expect(find.text('value 499'), findsNothing);
+
+ // Scrolling the page reaches the rest of the Output.
+ await tester.scrollUntilVisible(
+ find.text('value 499'),
+ 500,
+ // The page's own scroll view is the outermost of its scrollables.
+ scrollable: find
+ .descendant(
+ of: find.byKey(const Key('run-visit-body-summary')),
+ matching: find.byType(Scrollable),
+ )
+ .first,
+ );
+ expect(find.text('value 499'), findsOneWidget);
+ });
+
testWidgets('${platform.name} tabs show recorded values and exact empty '
'wording', (tester) async {
await openVisit(tester, platform);
- // Each field by name with its value, never raw JSON.
+ // Each field by name with its value, never raw JSON. Output is open at
+ // once; Input's value shows only after its tap.
expect(find.text('Ship it.'), findsNothing);
- expect(find.text('ok'), findsNothing);
+ expect(find.text('ok'), findsOneWidget);
await tester.tap(find.text('Input'));
await tester.pumpAndSettle();
expect(find.text('prompt'), findsOneWidget);
expect(find.text('Ship it.'), findsOneWidget);
expect(find.textContaining('"prompt"'), findsNothing);
+ // Output is open as the visit opens; no tap is needed to read it.
await openVisitTab(tester, RunVisitSection.output);
- await tester.tap(find.text('Output'));
- await tester.pumpAndSettle();
expect(find.text('result'), findsOneWidget);
expect(find.text('ok'), findsOneWidget);
@@ -127,13 +183,12 @@ void main() {
await openVisit(tester, platform, run: run);
expect(find.text(visitEmptyInput), findsNothing);
- expect(find.text(visitEmptyOutput), findsNothing);
+ // Output is open, so its empty sentence is already there.
+ expect(find.text(visitEmptyOutput), findsOneWidget);
await tester.tap(find.text('Input'));
await tester.pumpAndSettle();
expect(find.text(visitEmptyInput), findsOneWidget);
await openVisitTab(tester, RunVisitSection.output);
- await tester.tap(find.text('Output'));
- await tester.pumpAndSettle();
expect(find.text(visitEmptyOutput), findsOneWidget);
await openVisitTab(tester, RunVisitSection.artifacts);
expect(
diff --git a/app/test/features/runs/ui/run_detail_widget_test.dart b/app/test/features/runs/ui/run_detail_widget_test.dart
index 9767fb58..a8a81d03 100644
--- a/app/test/features/runs/ui/run_detail_widget_test.dart
+++ b/app/test/features/runs/ui/run_detail_widget_test.dart
@@ -172,7 +172,17 @@ void main() {
expect(find.text('alpha=1, items=1, 2'), findsOneWidget);
expect(find.textContaining('"alpha"'), findsNothing);
- await openSummarySection('Output');
+ // Output starts open: its value is there to scroll to, without a tap.
+ await tester.scrollUntilVisible(
+ find.text('ok=true'),
+ 200,
+ scrollable: find
+ .descendant(
+ of: find.byKey(const Key('run-detail-tab-body-summary')),
+ matching: find.byType(Scrollable),
+ )
+ .first,
+ );
expect(find.text('ok=true'), findsOneWidget);
await tapTab('Timeline');
diff --git a/app/test/features/runs/ui/run_search_selection_test.dart b/app/test/features/runs/ui/run_search_selection_test.dart
index 88711f80..b2d21c4a 100644
--- a/app/test/features/runs/ui/run_search_selection_test.dart
+++ b/app/test/features/runs/ui/run_search_selection_test.dart
@@ -263,7 +263,7 @@ void main() {
});
for (final platform in RunDetailTestPlatform.values) {
- testWidgets('${platform.name} input field expands only the input section', (
+ testWidgets('${platform.name} input field expands the input section', (
tester,
) async {
await pumpSelection(
@@ -277,7 +277,8 @@ void main() {
findsOneWidget,
);
expect(find.text('ship it'), findsOneWidget);
- expect(find.text('ok'), findsNothing);
+ // Output keeps its default: open, as every Summary opens.
+ expect(find.text('ok'), findsOneWidget);
});
testWidgets(
@@ -310,8 +311,9 @@ void main() {
find.byKey(const Key('run-detail-tab-body-summary')),
findsOneWidget,
);
+ // The plain Summary shows its default sections: Output open, Input closed.
expect(find.text('ship it'), findsNothing);
- expect(find.text('ok'), findsNothing);
+ expect(find.text('ok'), findsOneWidget);
});
for (final platform in RunDetailTestPlatform.values) {
@@ -337,8 +339,9 @@ void main() {
find.byKey(const Key('run-detail-tab-body-summary')),
findsOneWidget,
);
+ // The Summary's default sections: Output open, Input closed.
expect(find.text('ship it'), findsNothing);
- expect(find.text('ok'), findsNothing);
+ expect(find.text('ok'), findsOneWidget);
},
);
}
diff --git a/app/test/features/settings/keyboard_shortcuts_help_test.dart b/app/test/features/settings/keyboard_shortcuts_help_test.dart
index f070d2e7..1d6bd78a 100644
--- a/app/test/features/settings/keyboard_shortcuts_help_test.dart
+++ b/app/test/features/settings/keyboard_shortcuts_help_test.dart
@@ -40,6 +40,19 @@ void main() {
},
);
+ test('Runs and Pipelines switch is Ctrl+A on every platform', () {
+ for (final platform in TargetPlatform.values) {
+ final entry = KeyboardShortcutRegistry(platform: platform, web: false)
+ .entries
+ .firstWhere(
+ (entry) => entry.action == 'Switch between Runs and Pipelines',
+ );
+ expect(entry.keys, 'Ctrl+A', reason: platform.name);
+ expect(entry.caveat, contains('Pipelines'));
+ expect(entry.caveat, contains('text field'));
+ }
+ });
+
test('uses the shell primary modifier rule on iOS', () {
final entries = const KeyboardShortcutRegistry(
platform: TargetPlatform.iOS,
diff --git a/app/test/features/settings/settings_device_delivery_section_test.dart b/app/test/features/settings/settings_device_delivery_section_test.dart
index b6d9003d..42fba51f 100644
--- a/app/test/features/settings/settings_device_delivery_section_test.dart
+++ b/app/test/features/settings/settings_device_delivery_section_test.dart
@@ -18,6 +18,9 @@ Widget _host(
return MaterialApp(home: Scaffold(body: body));
}
+int _requests(FakeNotificationService service) =>
+ service.calls.where((call) => call.$1 == 'requestBatteryExemption').length;
+
bool _switchValue(WidgetTester tester) {
final tile = find.byKey(DeviceDeliveryKeys.toggle);
return tester.widget(tile).value;
@@ -62,9 +65,11 @@ void main() {
testWidgets('allow background delivery asks for the exemption', (
tester,
) async {
- final service = FakeNotificationService();
+ final service = FakeNotificationService()..batteryGranted = false;
await tester.pumpWidget(_host(service));
await tester.pumpAndSettle();
+ // The open-time prompt was declined; the row is the user's second try.
+ service.batteryGranted = true;
await tester.tap(find.text(deviceDeliveryBatteryLabel));
await tester.pumpAndSettle();
expect(
@@ -125,6 +130,157 @@ void main() {
await tester.pumpAndSettle();
expect(find.byKey(DeviceDeliveryKeys.error), findsOneWidget);
});
+
+ testWidgets(
+ 'a missing battery exemption keeps a warning row with the Samsung note',
+ (tester) async {
+ // The open-time prompt is declined, so the exemption stays missing.
+ final service = FakeNotificationService()..batteryGranted = false;
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ expect(find.byKey(DeviceDeliveryKeys.batteryWarning), findsOneWidget);
+ expect(find.text(deviceDeliveryWarningTitle), findsOneWidget);
+ expect(find.textContaining(deviceDeliverySamsungNote), findsOneWidget);
+ },
+ );
+
+ testWidgets('the warning goes away once the exemption is granted', (
+ tester,
+ ) async {
+ final service = FakeNotificationService()..batteryGranted = false;
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ expect(find.byKey(DeviceDeliveryKeys.batteryWarning), findsOneWidget);
+ service.batteryGranted = true;
+ await tester.tap(find.text(deviceDeliveryBatteryLabel));
+ await tester.pumpAndSettle();
+ expect(find.byKey(DeviceDeliveryKeys.batteryWarning), findsNothing);
+ });
+
+ testWidgets('switching on asks for the battery exemption before starting', (
+ tester,
+ ) async {
+ final service = FakeNotificationService();
+ service.current = service.copy(enabled: false, state: DeliveryState.off);
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ await tester.tap(find.byKey(DeviceDeliveryKeys.toggle));
+ await tester.pumpAndSettle();
+ final names = service.calls.map((call) => call.$1).toList();
+ expect(names, contains('requestBatteryExemption'));
+ expect(
+ names.indexOf('requestBatteryExemption'),
+ lessThan(names.indexOf('setEnabled')),
+ );
+ });
+
+ testWidgets(
+ 'opening Settings with delivery on and no exemption asks right away',
+ (tester) async {
+ final service = FakeNotificationService();
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ expect(_requests(service), 1);
+ expect(
+ find.text('Allowed: battery optimisation will not pause delivery'),
+ findsOneWidget,
+ );
+ expect(find.byKey(DeviceDeliveryKeys.batteryWarning), findsNothing);
+ },
+ );
+
+ testWidgets('a declined open-time prompt is not repeated on resume', (
+ tester,
+ ) async {
+ final service = FakeNotificationService()..batteryGranted = false;
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ expect(_requests(service), 1);
+ expect(find.byKey(DeviceDeliveryKeys.batteryWarning), findsOneWidget);
+ // Returning from the system screen re-reads the status only.
+ tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.inactive);
+ tester.binding.handleAppLifecycleStateChanged(AppLifecycleState.resumed);
+ await tester.pumpAndSettle();
+ expect(_requests(service), 1);
+ expect(find.byKey(DeviceDeliveryKeys.batteryWarning), findsOneWidget);
+ });
+
+ testWidgets('no open-time prompt when the exemption is already granted', (
+ tester,
+ ) async {
+ final service = FakeNotificationService();
+ service.current = service.copy(batteryExempt: true);
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ expect(_requests(service), 0);
+ });
+
+ testWidgets('no open-time prompt while delivery is off', (tester) async {
+ final service = FakeNotificationService();
+ service.current = service.copy(enabled: false, state: DeliveryState.off);
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ expect(_requests(service), 0);
+ });
+
+ testWidgets('no warning while delivery is off', (tester) async {
+ final service = FakeNotificationService();
+ service.current = service.copy(enabled: false, state: DeliveryState.off);
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ expect(find.byKey(DeviceDeliveryKeys.batteryWarning), findsNothing);
+ });
+
+ testWidgets('a refused session says the user must sign in again', (
+ tester,
+ ) async {
+ final service = FakeNotificationService();
+ service.current = service.copy(state: DeliveryState.signInRequired);
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ expect(
+ find.text('Sign in to Pipelines again to keep notifications'),
+ findsOneWidget,
+ );
+ });
+
+ testWidgets(
+ 'the connection log lists the service events, failures included',
+ (tester) async {
+ final service = FakeNotificationService();
+ service.events = [
+ NotificationConnectionEvent(
+ time: DateTime(2026, 11, 12, 9, 30, 5),
+ event: 'failed',
+ error: 'Expected HTTP 101',
+ code: 403,
+ ),
+ NotificationConnectionEvent(
+ time: DateTime(2026, 11, 12, 9, 29),
+ event: 'connected',
+ ),
+ ];
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text(deviceDeliveryLogTitle));
+ await tester.pumpAndSettle();
+ expect(find.text('Socket failed'), findsOneWidget);
+ expect(
+ find.textContaining('HTTP 403 · Expected HTTP 101'),
+ findsOneWidget,
+ );
+ expect(find.text('Socket opened'), findsOneWidget);
+ },
+ );
+
+ testWidgets('an empty connection log says so', (tester) async {
+ final service = FakeNotificationService();
+ await tester.pumpWidget(_host(service));
+ await tester.pumpAndSettle();
+ await tester.tap(find.text(deviceDeliveryLogTitle));
+ await tester.pumpAndSettle();
+ expect(find.text(deviceDeliveryLogEmpty), findsOneWidget);
+ });
}
class _FailingService extends FakeNotificationService {
diff --git a/app/test/features/settings/settings_walkthrough_test.dart b/app/test/features/settings/settings_walkthrough_test.dart
new file mode 100644
index 00000000..a769479d
--- /dev/null
+++ b/app/test/features/settings/settings_walkthrough_test.dart
@@ -0,0 +1,36 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/features/settings/settings_keys.dart';
+import 'package:pipelines_app/features/settings/settings_walkthrough_section.dart';
+import 'package:pipelines_app/ui/theme/app_theme.dart';
+
+void main() {
+ testWidgets('Settings reopens the walkthrough on the first page', (
+ tester,
+ ) async {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = const Size(390, 844);
+ addTearDown(tester.view.resetPhysicalSize);
+ addTearDown(tester.view.resetDevicePixelRatio);
+
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: appLightTheme(),
+ home: const Scaffold(body: SettingsWalkthroughSection()),
+ ),
+ );
+
+ expect(find.text('Show the walkthrough'), findsOneWidget);
+ expect(find.text('Welcome to Pipelines'), findsNothing);
+
+ await tester.tap(find.byKey(SettingsKeys.walkthrough));
+ await tester.pumpAndSettle();
+
+ expect(find.text('Welcome to Pipelines'), findsOneWidget);
+ expect(find.text('Step 1 of 4'), findsOneWidget);
+
+ await tester.tap(find.byKey(const ValueKey('walkthrough.skip')));
+ await tester.pumpAndSettle();
+ expect(find.text('Welcome to Pipelines'), findsNothing);
+ });
+}
diff --git a/app/test/features/terminal/terminal_chat_bar_action_test.dart b/app/test/features/terminal/terminal_chat_bar_action_test.dart
new file mode 100644
index 00000000..ac55adf1
--- /dev/null
+++ b/app/test/features/terminal/terminal_chat_bar_action_test.dart
@@ -0,0 +1,149 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/core/api_gateway.dart';
+import 'package:pipelines_app/features/chat/ui/sessions/chat_adaptive.dart';
+import 'package:pipelines_app/features/terminal/terminal_open_action.dart';
+import 'package:pipelines_app/features/terminal/terminal_scope.dart';
+import 'package:pipelines_app/features/terminal/terminal_toggle_button.dart';
+
+class _Actions implements TerminalActions {
+ int toggles = 0;
+
+ @override
+ void toggle() => toggles++;
+
+ @override
+ bool get claimsTabKeys => false;
+
+ @override
+ Future openAt(ApiGateway gateway, String cwd) async => null;
+}
+
+const _filesKey = ValueKey('files');
+const _terminalIdentifier = 'chat-terminal-toggle';
+
+/// Pumps an open chat's bar at [width]: Files, then whatever
+/// [terminalChatBarAction] builds (null on wide or with no terminal surface).
+/// Returns what it built.
+Future _pumpBar(
+ WidgetTester tester, {
+ required double width,
+ required ThemeData theme,
+ _Actions? actions,
+}) async {
+ Widget? built;
+ final bar = MediaQuery(
+ data: MediaQueryData(size: Size(width, 800)),
+ child: Scaffold(
+ body: Builder(
+ builder: (context) {
+ built = terminalChatBarAction(context);
+ return Row(
+ mainAxisAlignment: MainAxisAlignment.end,
+ children: [
+ ChatBarAction(
+ key: _filesKey,
+ label: 'Files',
+ onPressed: () {},
+ materialIcon: Icons.folder_outlined,
+ ),
+ ?built,
+ ],
+ );
+ },
+ ),
+ ),
+ );
+ await tester.pumpWidget(
+ MaterialApp(
+ theme: theme,
+ home: actions == null
+ ? bar
+ : TerminalScope(actions: actions, child: bar),
+ ),
+ );
+ await tester.pump();
+ return built;
+}
+
+/// The colour an icon inside [finder] resolves to in the current theme.
+Color? _iconColor(WidgetTester tester, Finder finder) {
+ final icon = find.descendant(of: finder, matching: find.byType(Icon));
+ final element = tester.element(icon);
+ return tester.widget(icon).color ?? IconTheme.of(element).color;
+}
+
+void main() {
+ for (final theme in [
+ ThemeData(brightness: Brightness.light, useMaterial3: true),
+ ThemeData(brightness: Brightness.dark, useMaterial3: true),
+ ]) {
+ final mode = theme.brightness.name;
+
+ testWidgets('$mode, phone: an open chat has a terminal button beside '
+ 'Files, styled as Files', (tester) async {
+ final actions = _Actions();
+ final built = await _pumpBar(
+ tester,
+ width: 390,
+ theme: theme,
+ actions: actions,
+ );
+ expect(built, isA());
+
+ final terminal = find.bySemanticsIdentifier(_terminalIdentifier);
+ final files = find.byKey(_filesKey);
+ expect(terminal, findsOneWidget);
+ expect(
+ tester.getSize(terminal),
+ tester.getSize(files),
+ reason: 'the terminal button must be the same size as Files',
+ );
+ expect(
+ _iconColor(tester, terminal),
+ _iconColor(tester, files),
+ reason: 'the terminal icon must share the colour of Files',
+ );
+ expect(
+ tester
+ .widget(
+ find.descendant(of: terminal, matching: find.byType(IconButton)),
+ )
+ .isSelected,
+ isNull,
+ reason: 'the terminal must not be a selected (tinted) button',
+ );
+ expect(find.byTooltip(TerminalToggleButton.label), findsOneWidget);
+ });
+
+ testWidgets('$mode, phone: tapping the terminal button toggles the '
+ 'terminal', (tester) async {
+ final actions = _Actions();
+ await _pumpBar(tester, width: 390, theme: theme, actions: actions);
+
+ await tester.tap(find.byTooltip(TerminalToggleButton.label));
+ await tester.pump();
+ expect(actions.toggles, 1);
+ });
+
+ testWidgets('$mode, wide: the open chat bar has no terminal button (the '
+ 'shell bar keeps it)', (tester) async {
+ final built = await _pumpBar(
+ tester,
+ width: 1000,
+ theme: theme,
+ actions: _Actions(),
+ );
+ expect(built, isNull);
+ expect(find.bySemanticsIdentifier(_terminalIdentifier), findsNothing);
+ });
+
+ testWidgets('$mode, phone without a terminal surface: no terminal button', (
+ tester,
+ ) async {
+ final built = await _pumpBar(tester, width: 390, theme: theme);
+ expect(built, isNull);
+ expect(find.bySemanticsIdentifier(_terminalIdentifier), findsNothing);
+ });
+ }
+}
diff --git a/app/test/features/terminal/terminal_surface_test.dart b/app/test/features/terminal/terminal_surface_test.dart
index fff954a5..f029887d 100644
--- a/app/test/features/terminal/terminal_surface_test.dart
+++ b/app/test/features/terminal/terminal_surface_test.dart
@@ -167,10 +167,12 @@ void main() {
expect(floatFinder, findsOneWidget);
expect(frame().size, start.size + const Offset(80, 50));
- await tester.tap(find.byTooltip('Close'));
+ // The X minimises too: the window stays listed, hidden, with its shells.
+ await tester.tap(find.byTooltip('Minimise'));
await tester.pumpAndSettle();
expect(layout.visible, isFalse);
- expect(manager.windows, isEmpty);
+ expect(manager.windows.single.minimized, isTrue);
+ expect(floatFinder, findsNothing);
expect(hub.tabs, hasLength(2));
await ctrlBacktick(tester);
expect(floatFinder, findsOneWidget);
diff --git a/app/test/features/terminal/terminal_toggle_button_test.dart b/app/test/features/terminal/terminal_toggle_button_test.dart
new file mode 100644
index 00000000..ce52c513
--- /dev/null
+++ b/app/test/features/terminal/terminal_toggle_button_test.dart
@@ -0,0 +1,123 @@
+import 'dart:ui' as ui;
+import 'package:flutter/material.dart';
+import 'package:flutter/semantics.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/core/api_gateway.dart';
+import 'package:pipelines_app/features/chat/ui/sessions/chat_adaptive.dart';
+import 'package:pipelines_app/features/terminal/terminal_layout.dart';
+import 'package:pipelines_app/features/terminal/terminal_scope.dart';
+import 'package:pipelines_app/features/terminal/terminal_toggle_button.dart';
+
+import 'terminal_fixtures.dart';
+
+class _Actions implements TerminalActions {
+ int toggles = 0;
+
+ @override
+ void toggle() => toggles++;
+
+ @override
+ bool get claimsTabKeys => false;
+
+ @override
+ Future openAt(ApiGateway gateway, String cwd) async => null;
+}
+
+const _filesKey = ValueKey('files');
+const _terminalKey = ValueKey('shell.terminal');
+
+/// A chat's bar: Files beside the terminal toggle, as the shell shows them.
+Widget _bar(TerminalLayout layout, _Actions actions, ThemeData theme) =>
+ MaterialApp(
+ theme: theme,
+ home: TerminalScope(
+ actions: actions,
+ child: Scaffold(
+ body: Row(
+ mainAxisAlignment: MainAxisAlignment.end,
+ children: [
+ ChatBarAction(
+ key: _filesKey,
+ label: 'Files',
+ onPressed: () {},
+ materialIcon: Icons.folder_outlined,
+ ),
+ TerminalToggleButton(layout: layout),
+ ],
+ ),
+ ),
+ ),
+ );
+
+/// The colour an icon inside [finder] resolves to in the current theme.
+Color? _iconColor(WidgetTester tester, Finder finder) {
+ final icon = find.descendant(of: finder, matching: find.byType(Icon));
+ final element = tester.element(icon);
+ return tester.widget(icon).color ?? IconTheme.of(element).color;
+}
+
+/// Whether the terminal button's semantics (or one of its merged parents)
+/// is announced as toggled on.
+bool _toggled(WidgetTester tester) {
+ for (
+ SemanticsNode? node = tester.getSemantics(
+ find.byTooltip(TerminalToggleButton.label),
+ );
+ node != null;
+ node = node.parent
+ ) {
+ if (node.flagsCollection.isToggled == ui.Tristate.isTrue) return true;
+ }
+ return false;
+}
+
+void main() {
+ for (final theme in [
+ ThemeData(brightness: Brightness.light, useMaterial3: true),
+ ThemeData(brightness: Brightness.dark, useMaterial3: true),
+ ]) {
+ final mode = theme.brightness.name;
+
+ testWidgets('$mode: the terminal button is a plain bar button, shown or '
+ 'hidden, like Files', (tester) async {
+ final layout = TerminalLayout(store: MemoryLayoutStore());
+ final actions = _Actions();
+ await tester.pumpWidget(_bar(layout, actions, theme));
+ await tester.pump();
+
+ final files = find.byKey(_filesKey);
+ final terminal = find.byKey(_terminalKey);
+ for (final shown in [false, true]) {
+ if (shown) layout.show();
+ await tester.pump();
+
+ final button = tester.widget(terminal);
+ expect(button.isSelected, isNull, reason: 'shown: $shown');
+ expect(
+ _iconColor(tester, terminal),
+ _iconColor(tester, files),
+ reason: 'icon colour differs from Files (shown: $shown)',
+ );
+ expect(tester.getSize(terminal), tester.getSize(files));
+ }
+ });
+
+ testWidgets('$mode: the shown state is announced without a tint', (
+ tester,
+ ) async {
+ final handle = tester.ensureSemantics();
+ final layout = TerminalLayout(store: MemoryLayoutStore());
+ final actions = _Actions();
+ await tester.pumpWidget(_bar(layout, actions, theme));
+ await tester.pump();
+
+ expect(_toggled(tester), isFalse);
+ layout.show();
+ await tester.pump();
+ expect(_toggled(tester), isTrue);
+ await tester.tap(find.byKey(_terminalKey));
+ expect(actions.toggles, 1);
+ handle.dispose();
+ });
+ }
+}
diff --git a/app/test/features/walkthrough/first_run_walkthrough_test.dart b/app/test/features/walkthrough/first_run_walkthrough_test.dart
new file mode 100644
index 00000000..ddeaec1a
--- /dev/null
+++ b/app/test/features/walkthrough/first_run_walkthrough_test.dart
@@ -0,0 +1,202 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/features/walkthrough/first_run_walkthrough.dart';
+import 'package:pipelines_app/features/walkthrough/walkthrough_steps.dart';
+import 'package:pipelines_app/ui/theme/app_theme.dart';
+
+const _nextKey = ValueKey('walkthrough.next');
+const _backKey = ValueKey('walkthrough.back');
+const _skipKey = ValueKey('walkthrough.skip');
+const _copyKey = ValueKey('walkthrough.copy');
+const _commandKey = ValueKey('walkthrough.command');
+const _launchKey = ValueKey('launch');
+
+Widget _launcher({ThemeMode mode = ThemeMode.light, double textScale = 1}) =>
+ MaterialApp(
+ theme: appLightTheme(),
+ darkTheme: appDarkTheme(),
+ themeMode: mode,
+ builder: (context, child) => MediaQuery(
+ data: MediaQuery.of(
+ context,
+ ).copyWith(textScaler: TextScaler.linear(textScale)),
+ child: child!,
+ ),
+ home: Scaffold(
+ body: Builder(
+ builder: (context) => Center(
+ child: FilledButton(
+ key: _launchKey,
+ onPressed: () => showFirstRunWalkthrough(context),
+ child: const Text('Open'),
+ ),
+ ),
+ ),
+ ),
+ );
+
+Future _open(WidgetTester tester) async {
+ await tester.tap(find.byKey(_launchKey));
+ await tester.pumpAndSettle();
+}
+
+void _useViewport(WidgetTester tester, Size size) {
+ tester.view.devicePixelRatio = 1;
+ tester.view.physicalSize = size;
+ addTearDown(tester.view.resetPhysicalSize);
+ addTearDown(tester.view.resetDevicePixelRatio);
+}
+
+void main() {
+ group('phone layout', () {
+ testWidgets('opens as a bottom sheet with the first page', (tester) async {
+ _useViewport(tester, const Size(390, 844));
+ await tester.pumpWidget(_launcher());
+ await _open(tester);
+
+ expect(find.byType(BottomSheet), findsOneWidget);
+ expect(find.byType(Dialog), findsNothing);
+ expect(find.text('Step 1 of 4'), findsOneWidget);
+ expect(find.text(walkthroughSteps.first.title), findsOneWidget);
+ });
+
+ testWidgets('Back is disabled on the first page; Next advances', (
+ tester,
+ ) async {
+ _useViewport(tester, const Size(390, 844));
+ await tester.pumpWidget(_launcher());
+ await _open(tester);
+
+ expect(tester.widget(find.byKey(_backKey)).onPressed, isNull);
+ await tester.tap(find.byKey(_nextKey));
+ await tester.pumpAndSettle();
+ expect(find.text('Step 2 of 4'), findsOneWidget);
+ expect(
+ tester.widget(find.byKey(_backKey)).onPressed,
+ isNotNull,
+ );
+
+ await tester.tap(find.byKey(_backKey));
+ await tester.pumpAndSettle();
+ expect(find.text('Step 1 of 4'), findsOneWidget);
+ });
+
+ testWidgets('walks four pages, Done on the last, Skip on every page', (
+ tester,
+ ) async {
+ _useViewport(tester, const Size(390, 844));
+ await tester.pumpWidget(_launcher());
+ await _open(tester);
+
+ for (var page = 0; page < 3; page++) {
+ expect(find.byKey(_skipKey), findsOneWidget);
+ expect(find.text('Next'), findsOneWidget);
+ await tester.tap(find.byKey(_nextKey));
+ await tester.pumpAndSettle();
+ }
+ expect(find.text('Step 4 of 4'), findsOneWidget);
+ expect(find.text('Done'), findsOneWidget);
+ expect(find.byKey(_skipKey), findsOneWidget);
+ expect(find.text(walkthroughSteps.last.title), findsOneWidget);
+
+ await tester.tap(find.text('Done'));
+ await tester.pumpAndSettle();
+ expect(find.text(walkthroughSteps.last.title), findsNothing);
+ });
+
+ testWidgets('Skip closes from the middle of the walkthrough', (
+ tester,
+ ) async {
+ _useViewport(tester, const Size(390, 844));
+ await tester.pumpWidget(_launcher());
+ await _open(tester);
+ await tester.tap(find.byKey(_nextKey));
+ await tester.pumpAndSettle();
+
+ await tester.tap(find.byKey(_skipKey));
+ await tester.pumpAndSettle();
+ expect(find.byType(BottomSheet), findsNothing);
+ });
+ });
+
+ testWidgets('wide windows open the walkthrough as a dialog', (tester) async {
+ _useViewport(tester, const Size(1280, 900));
+ await tester.pumpWidget(_launcher());
+ await _open(tester);
+
+ expect(find.byType(Dialog), findsOneWidget);
+ expect(find.byType(BottomSheet), findsNothing);
+ expect(find.text('Step 1 of 4'), findsOneWidget);
+ await tester.tap(find.byKey(_nextKey));
+ await tester.pumpAndSettle();
+ expect(find.text(walkthroughSteps[1].title), findsOneWidget);
+ });
+
+ testWidgets('the harness page offers each agent and copies its command', (
+ tester,
+ ) async {
+ _useViewport(tester, const Size(390, 844));
+ final copied = [];
+ TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+ .setMockMethodCallHandler(SystemChannels.platform, (call) async {
+ if (call.method == 'Clipboard.setData') {
+ copied.add((call.arguments as Map)['text'] as String);
+ }
+ return null;
+ });
+ addTearDown(
+ () => TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger
+ .setMockMethodCallHandler(SystemChannels.platform, null),
+ );
+
+ await tester.pumpWidget(_launcher());
+ await _open(tester);
+ await tester.tap(find.byKey(_nextKey));
+ await tester.pumpAndSettle();
+
+ expect(
+ tester.widget(find.byKey(_commandKey)).data,
+ 'pipelines harness setup claude',
+ );
+ await tester.tap(
+ find.byKey(const ValueKey('walkthrough.agent.pi')),
+ );
+ await tester.pumpAndSettle();
+ expect(
+ tester.widget(find.byKey(_commandKey)).data,
+ 'pipelines harness setup pi',
+ );
+
+ await tester.tap(find.byKey(_copyKey));
+ await tester.pumpAndSettle();
+ expect(copied, ['pipelines harness setup pi']);
+ expect(
+ find.descendant(
+ of: find.byKey(_copyKey),
+ matching: find.byIcon(Icons.check),
+ ),
+ findsOneWidget,
+ );
+ });
+
+ testWidgets('large text and dark mode lay out without overflow', (
+ tester,
+ ) async {
+ _useViewport(tester, const Size(360, 740));
+ await tester.pumpWidget(_launcher(mode: ThemeMode.dark, textScale: 2));
+ await _open(tester);
+
+ for (var page = 0; page < walkthroughSteps.length; page++) {
+ expect(tester.takeException(), isNull, reason: 'page $page');
+ expect(find.text(walkthroughSteps[page].title), findsOneWidget);
+ if (page < walkthroughSteps.length - 1) {
+ // At 2x text the phone sheet scrolls, so Next can start off screen.
+ await tester.ensureVisible(find.byKey(_nextKey));
+ await tester.tap(find.byKey(_nextKey));
+ await tester.pumpAndSettle();
+ }
+ }
+ expect(tester.takeException(), isNull);
+ });
+}
diff --git a/app/test/features/walkthrough/walkthrough_gate_test.dart b/app/test/features/walkthrough/walkthrough_gate_test.dart
new file mode 100644
index 00000000..72dc748b
--- /dev/null
+++ b/app/test/features/walkthrough/walkthrough_gate_test.dart
@@ -0,0 +1,341 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/core/api_gateway.dart';
+import 'package:pipelines_app/features/walkthrough/walkthrough_gate.dart';
+import 'package:pipelines_app/features/walkthrough/walkthrough_store.dart';
+import 'package:pipelines_app/ui/theme/app_theme.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+const _welcome = 'Welcome to Pipelines';
+
+Future _noPreferences() async => null;
+
+/// A gateway that answers the three empty-server list calls from fixed lists.
+class _FakeGateway implements ApiGateway {
+ _FakeGateway({this.runs = const [], this.failing = false});
+
+ /// Runs the server reports; pipelines and chats are always empty here.
+ final List runs;
+ bool failing;
+ final calls = [];
+
+ @override
+ Future call(String type, [JsonMap fields = const {}]) async {
+ calls.add(type);
+ if (failing) throw StateError('offline');
+ return switch (type) {
+ 'list_pipelines' => {'pipelines': const []},
+ 'list_runs' => {'runs': runs},
+ 'chat_sessions' => {'chat_sessions': const []},
+ _ => {'type': 'error'},
+ };
+ }
+
+ @override
+ Stream get frames => const Stream.empty();
+}
+
+/// Delegates to [inner], but holds [isSeen] until [release] so a test can
+/// change the page visibility while an offer is still in flight.
+class _HeldStore implements WalkthroughStore {
+ _HeldStore(this.inner);
+
+ final MemoryWalkthroughStore inner;
+ Completer? _gate;
+
+ void hold() => _gate = Completer();
+
+ void release() {
+ _gate?.complete();
+ _gate = null;
+ }
+
+ @override
+ Future isSeen() async {
+ await _gate?.future;
+ return inner.isSeen();
+ }
+
+ @override
+ Future markSeen() => inner.markSeen();
+
+ @override
+ Future wasOffered(String serverScope) =>
+ inner.wasOffered(serverScope);
+
+ @override
+ Future markOffered(String serverScope) =>
+ inner.markOffered(serverScope);
+}
+
+/// [link] stands in for the session: its value is whether the server connected,
+/// and notifying it is the connection transition. Defaults to connected.
+Widget _host({
+ required WalkthroughStore store,
+ ApiGateway? gateway,
+ bool enabled = true,
+ ValueNotifier? link,
+}) {
+ final session = link ?? ValueNotifier(true);
+ return MaterialApp(
+ theme: appLightTheme(),
+ darkTheme: appDarkTheme(),
+ home: Scaffold(
+ body: FirstRunWalkthroughGate(
+ store: store,
+ enabled: enabled,
+ serverScope: 'server-a',
+ connection: session,
+ connected: () => session.value,
+ gateway: gateway,
+ child: const Text('Pipelines page'),
+ ),
+ ),
+ );
+}
+
+Future _finishWalkthrough(WidgetTester tester) async {
+ for (var page = 0; page < 3; page++) {
+ await tester.tap(find.byKey(const ValueKey('walkthrough.next')));
+ await tester.pumpAndSettle();
+ }
+ await tester.tap(find.text('Done'));
+ await tester.pumpAndSettle();
+}
+
+void main() {
+ testWidgets('first launch shows the walkthrough once per device', (
+ tester,
+ ) async {
+ final store = MemoryWalkthroughStore();
+ await tester.pumpWidget(_host(store: store));
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsOneWidget);
+
+ await _finishWalkthrough(tester);
+ expect(find.text(_welcome), findsNothing);
+ expect(store.seen, isTrue);
+
+ // A later launch on the same device does not show it again.
+ await tester.pumpWidget(const SizedBox());
+ await tester.pumpWidget(_host(store: store));
+ await tester.pumpAndSettle();
+ expect(find.text(_welcome), findsNothing);
+ expect(find.text('Pipelines page'), findsOneWidget);
+ });
+
+ testWidgets('Done persists the seen record and no server query runs', (
+ tester,
+ ) async {
+ final store = MemoryWalkthroughStore();
+ final gateway = _FakeGateway();
+ await tester.pumpWidget(_host(store: store, gateway: gateway));
+ await tester.pumpAndSettle();
+ await _finishWalkthrough(tester);
+
+ expect(store.seen, isTrue);
+ expect(
+ gateway.calls,
+ isEmpty,
+ reason: 'first launch needs no server check',
+ );
+ });
+
+ testWidgets('Skip on the first page persists the seen record', (
+ tester,
+ ) async {
+ final store = MemoryWalkthroughStore();
+ await tester.pumpWidget(_host(store: store));
+ await tester.pumpAndSettle();
+
+ await tester.tap(find.byKey(const ValueKey('walkthrough.skip')));
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsNothing);
+ expect(store.seen, isTrue);
+ });
+
+ testWidgets('a seen device on an empty server is offered it once', (
+ tester,
+ ) async {
+ final store = MemoryWalkthroughStore(seen: true);
+ final gateway = _FakeGateway();
+ await tester.pumpWidget(_host(store: store, gateway: gateway));
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsOneWidget);
+ expect(store.offered, {'server-a'});
+ expect(
+ gateway.calls,
+ containsAll(['list_pipelines', 'list_runs', 'chat_sessions']),
+ );
+
+ await tester.tap(find.byKey(const ValueKey('walkthrough.skip')));
+ await tester.pumpAndSettle();
+
+ // The server was offered already, so a fresh mount stays quiet.
+ await tester.pumpWidget(const SizedBox());
+ await tester.pumpWidget(_host(store: store, gateway: gateway));
+ await tester.pumpAndSettle();
+ expect(find.text(_welcome), findsNothing);
+ });
+
+ testWidgets(
+ 'a seen device that starts disconnected is offered once it connects',
+ (tester) async {
+ // Startup order in the app: the Pipelines page mounts before the session
+ // has connected. The server must not be asked yet, and the offer must
+ // still happen after the connection arrives.
+ final store = MemoryWalkthroughStore(seen: true);
+ final gateway = _FakeGateway();
+ final link = ValueNotifier(false);
+ await tester.pumpWidget(
+ _host(store: store, gateway: gateway, link: link),
+ );
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsNothing);
+ expect(
+ gateway.calls,
+ isEmpty,
+ reason: 'no server call while disconnected',
+ );
+ expect(store.offered, isEmpty);
+
+ link.value = true;
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsOneWidget);
+ expect(store.offered, {'server-a'});
+ expect(
+ gateway.calls,
+ containsAll(['list_pipelines', 'list_runs', 'chat_sessions']),
+ );
+ },
+ );
+
+ testWidgets('an unreadable check is retried on the next connection', (
+ tester,
+ ) async {
+ final store = MemoryWalkthroughStore(seen: true);
+ final gateway = _FakeGateway(failing: true);
+ final link = ValueNotifier(true);
+ await tester.pumpWidget(_host(store: store, gateway: gateway, link: link));
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsNothing);
+ expect(store.offered, isEmpty);
+ final callsAfterFailure = gateway.calls.length;
+
+ // A repeated notification while still connected does not re-query.
+ link.notifyListeners();
+ await tester.pumpAndSettle();
+ expect(gateway.calls.length, callsAfterFailure);
+
+ // The server recovers; a fresh connection runs the check and offers it.
+ gateway.failing = false;
+ link.value = false;
+ await tester.pumpAndSettle();
+ link.value = true;
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsOneWidget);
+ expect(store.offered, {'server-a'});
+ });
+
+ testWidgets('a seen device on a server with work is not offered', (
+ tester,
+ ) async {
+ final store = MemoryWalkthroughStore(seen: true);
+ final gateway = _FakeGateway(
+ runs: [
+ {'id': 'run-1'},
+ ],
+ );
+ await tester.pumpWidget(_host(store: store, gateway: gateway));
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsNothing);
+ expect(store.offered, isEmpty);
+ });
+
+ testWidgets('an unreadable server never triggers the walkthrough', (
+ tester,
+ ) async {
+ final store = MemoryWalkthroughStore(seen: true);
+ await tester.pumpWidget(
+ _host(store: store, gateway: _FakeGateway(failing: true)),
+ );
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsNothing);
+ expect(store.offered, isEmpty);
+ });
+
+ testWidgets('the Pipelines page being hidden defers the check', (
+ tester,
+ ) async {
+ final store = MemoryWalkthroughStore();
+ await tester.pumpWidget(_host(store: store, enabled: false));
+ await tester.pumpAndSettle();
+ expect(find.text(_welcome), findsNothing);
+ expect(store.seen, isFalse);
+
+ await tester.pumpWidget(_host(store: store, enabled: true));
+ await tester.pumpAndSettle();
+ expect(find.text(_welcome), findsOneWidget);
+ });
+
+ testWidgets(
+ 'hiding Pipelines while an offer is pending keeps the walkthrough closed',
+ (tester) async {
+ final inner = MemoryWalkthroughStore();
+ final store = _HeldStore(inner)..hold();
+ await tester.pumpWidget(_host(store: store));
+ await tester.pump();
+
+ // The Pipelines page is hidden while the offer is still reading the store.
+ await tester.pumpWidget(_host(store: store, enabled: false));
+ store.release();
+ await tester.pumpAndSettle();
+
+ expect(find.text(_welcome), findsNothing);
+ expect(inner.seen, isFalse);
+
+ // Showing Pipelines again offers it once, on the same mount.
+ await tester.pumpWidget(_host(store: store, enabled: true));
+ await tester.pumpAndSettle();
+ expect(find.text(_welcome), findsOneWidget);
+ },
+ );
+
+ test('an unavailable preference store reports seen and offered', () async {
+ // The opener yields no preferences, as when the platform store is absent:
+ // every read reports "seen" and every write is quietly dropped.
+ const store = SharedPreferencesWalkthroughStore(open: _noPreferences);
+ expect(await store.isSeen(), isTrue);
+ expect(await store.wasOffered('server-a'), isTrue);
+ await store.markSeen();
+ await store.markOffered('server-a');
+ expect(await store.isSeen(), isTrue);
+ });
+
+ test(
+ 'SharedPreferences store records seen and offered under the keys',
+ () async {
+ SharedPreferences.setMockInitialValues({});
+ const store = SharedPreferencesWalkthroughStore();
+ expect(await store.isSeen(), isFalse);
+ await store.markSeen();
+ expect(await store.isSeen(), isTrue);
+
+ expect(await store.wasOffered('server-a'), isFalse);
+ await store.markOffered('server-a');
+ expect(await store.wasOffered('server-a'), isTrue);
+ expect(await store.wasOffered('server-b'), isFalse);
+ },
+ );
+}
diff --git a/app/test/shell/attention_badge_test.dart b/app/test/shell/attention_badge_test.dart
index 66348283..fd70c6d0 100644
--- a/app/test/shell/attention_badge_test.dart
+++ b/app/test/shell/attention_badge_test.dart
@@ -22,13 +22,16 @@ void main() {
}
for (final width in [390.0, 1000.0]) {
- final mount = width < 600 ? 'bottom bar' : 'wide bar';
+ final mount = width < 600 ? 'bottom bar' : 'rail';
+ // The rail (wide) or the floating bar (phone) carries the same counts.
+ final navigation = width < 600
+ ? find.byType(FloatingDestinationBar)
+ : find.byType(NavigationRail);
testWidgets('$mount shows the count on the Runs tab', (tester) async {
final semantics = tester.ensureSemantics();
await pumpShell(tester, width: width, count: 3);
- expect(find.byType(FloatingDestinationBar), findsOneWidget);
- expect(find.byType(NavigationRail), findsNothing);
+ expect(navigation, findsOneWidget);
final badge = find.byKey(const ValueKey('shell.badge.runs.running'));
expect(badge, findsOneWidget);
expect(
diff --git a/app/test/shell/floating_tab_bar_test.dart b/app/test/shell/floating_tab_bar_test.dart
index ff55d732..6a0a8dfc 100644
--- a/app/test/shell/floating_tab_bar_test.dart
+++ b/app/test/shell/floating_tab_bar_test.dart
@@ -110,22 +110,23 @@ void main() {
testWidgets('wide leading bar under the list, content '
'keeps the width and taps beside the bar reach it', (tester) async {
taps = 0;
- await setSize(tester, const Size(1200, 800));
+ await setSize(tester, const Size(640, 800));
await tester.pumpWidget(shell());
final rect = tester.getRect(pill());
// With no item open the bar still sits under the list column, where it
// sits beside an open item, so it never jumps sides.
expect(rect.left, moreOrLessEquals(kFloatingBarMargin, epsilon: 0.5));
expect(rect.bottom, 800 - 16);
- expect(rect.width, lessThan(1200 * 0.6));
+ expect(rect.width, lessThan(640 * 0.6));
// Captions participate in the bar's content-driven width.
await expectLabeledTargets(tester, rect);
await expectNoSharedBackdrop(tester);
expect(
rect.width,
- lessThanOrEqualTo(listDetailListWidth(1200, 1200, null) - 2 * 16),
+ lessThanOrEqualTo(listDetailListWidth(640, 640, null) - 2 * 16),
);
- // No rail or sidebar: the content starts at the left edge.
+ // Below the rail's window width (see kNavigationRailMinWindowWidth) the
+ // floating bar still sits under the list: no rail, content at the left edge.
expect(find.byType(NavigationRail), findsNothing);
expect(tester.getRect(find.byKey(const Key('content'))).left, 0);
// Beside the bar, at the bar's height, the content takes the tap.
@@ -141,7 +142,7 @@ void main() {
testWidgets('content learns the bar height as bottom padding', (
tester,
) async {
- for (final size in const [Size(390, 844), Size(1200, 800)]) {
+ for (final size in const [Size(390, 844), Size(640, 800)]) {
await setSize(tester, size);
await tester.pumpWidget(shell());
await tester.pump();
@@ -166,13 +167,13 @@ void main() {
expect(find.text('taps 1'), findsOneWidget);
final state = tester.state(find.byType(StatefulBuilder));
- tester.view.physicalSize = const Size(1200, 800);
+ tester.view.physicalSize = const Size(640, 800);
await tester.pump();
expect(
tester.getRect(pill()).left,
moreOrLessEquals(kFloatingBarMargin, epsilon: 0.5),
);
- expect(tester.getRect(pill()).width, lessThan(1200 * 0.6));
+ expect(tester.getRect(pill()).width, lessThan(640 * 0.6));
expect(tester.state(find.byType(StatefulBuilder)), same(state));
tester.view.physicalSize = const Size(390, 844);
diff --git a/app/test/shell/list_pane_resize_test.dart b/app/test/shell/list_pane_resize_test.dart
index 1e961bfb..a43c516b 100644
--- a/app/test/shell/list_pane_resize_test.dart
+++ b/app/test/shell/list_pane_resize_test.dart
@@ -8,6 +8,7 @@ import 'package:pipelines_app/shell/destination.dart';
import 'package:pipelines_app/shell/list_detail.dart';
import 'package:pipelines_app/shell/list_pane_divider.dart';
import 'package:pipelines_app/shell/list_pane_widths.dart';
+import 'package:pipelines_app/shell/navigation_rail.dart';
import 'package:pipelines_app/shell/shell_bar.dart';
import 'package:pipelines_app/ui/adaptive/resize_grip.dart';
@@ -66,6 +67,7 @@ void main() {
testWidgets('dragging resizes the list live, the shell bar '
'follows, and the width clamps', (tester) async {
await setSize(tester, const Size(1200, 800));
+ const body = 1200 - kNavigationRailSpace;
final store = MemoryListPaneWidthStore();
await tester.pumpWidget(shell(store: store));
await settle(tester);
@@ -79,7 +81,7 @@ void main() {
// Live, before the drag ends; nothing saved yet.
expect(listWidth(tester), closeTo(340, 0.5));
expect(shellBarWidth(tester), closeTo(340, 0.5));
- expect(bodyWidth(tester), closeTo(1200 - 1 - 340, 0.5));
+ expect(bodyWidth(tester), closeTo(body - 1 - 340, 0.5));
expect(store.values, isEmpty);
await gesture.up();
await tester.pump();
@@ -92,9 +94,10 @@ void main() {
// ...nor wider than leaves the open item half the window.
await tester.drag(divider, const Offset(900, 0));
await settle(tester);
- expect(listWidth(tester), closeTo(1200 - 1 - 600, 0.5));
- expect(shellBarWidth(tester), closeTo(599, 0.5));
- expect(store.values['runs'], closeTo(599, 0.5));
+ // Half of the body for the open item, the list the rest.
+ expect(listWidth(tester), closeTo(body - 1 - body * 0.5, 0.5));
+ expect(shellBarWidth(tester), closeTo(body - 1 - body * 0.5, 0.5));
+ expect(store.values['runs'], closeTo(body - 1 - body * 0.5, 0.5));
});
testWidgets('a double tap returns to the default policy', (tester) async {
@@ -143,8 +146,11 @@ void main() {
final store = MemoryListPaneWidthStore({'runs': 600});
await tester.pumpWidget(shell(store: store));
await settle(tester);
- expect(listWidth(tester), closeTo(1000 - 1 - 500, 0.5));
- expect(shellBarWidth(tester), closeTo(499, 0.5));
+ // Beside the destination rail the panes lay out in the window's width
+ // less the rail, so the clamp is the body's: half of it for the open item.
+ const body = 1000 - kNavigationRailSpace;
+ expect(listWidth(tester), closeTo(body - 1 - body * 0.5, 0.5));
+ expect(shellBarWidth(tester), closeTo(body - 1 - body * 0.5, 0.5));
expect(store.values['runs'], 600);
await setSize(tester, const Size(1600, 800));
@@ -212,7 +218,8 @@ void main() {
expect(grip().emphasized, isFalse);
Focus.of(tester.element(divider)).requestFocus();
- await tester.pump();
+ // The focus change reaches the grip one frame later beside the rail.
+ await tester.pumpAndSettle();
expect(grip().emphasized, isTrue);
});
diff --git a/app/test/shell/navigation_rail_test.dart b/app/test/shell/navigation_rail_test.dart
new file mode 100644
index 00000000..3b6030f7
--- /dev/null
+++ b/app/test/shell/navigation_rail_test.dart
@@ -0,0 +1,283 @@
+import 'dart:ui' show Tristate;
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/shell/adaptive_shell.dart';
+import 'package:pipelines_app/shell/destination.dart';
+import 'package:pipelines_app/shell/list_detail.dart';
+import 'package:pipelines_app/shell/navigation_rail.dart';
+import 'package:pipelines_app/shell/shell_bar.dart';
+import 'package:pipelines_app/shell/windows/window_host.dart';
+import 'package:pipelines_app/ui/adaptive/floating_destination_bar.dart';
+
+import 'windows/window_test_harness.dart';
+
+/// On a wide window the destinations sit in a Material navigation rail at the
+/// left edge (Settings pinned to its foot); narrower windows keep the floating
+/// bar. The rail keeps the badges and the keys of the bar it replaces.
+void main() {
+ Future pumpShell(
+ WidgetTester tester, {
+ required double width,
+ double height = 800,
+ int runningRunCount = 0,
+ bool withPanes = false,
+ }) async {
+ tester.view.physicalSize = Size(width, height);
+ tester.view.devicePixelRatio = 1;
+ addTearDown(tester.view.resetPhysicalSize);
+ addTearDown(tester.view.resetDevicePixelRatio);
+ final shell = AdaptiveShell(
+ destination: withPanes ? AppDestination.runs : AppDestination.pipelines,
+ runningRunCount: runningRunCount,
+ destinationBodies: {
+ AppDestination.pipelines: (_) => const Text('pipelines body'),
+ AppDestination.runs: (_) => withPanes
+ ? ListDetailPanes(
+ list: const ShellBar(child: Text('runs list')),
+ detail: const Center(child: Text('runs detail')),
+ )
+ : const Text('runs body'),
+ AppDestination.chat: (_) => const Text('chat body'),
+ AppDestination.search: (_) => const Text('search body'),
+ AppDestination.settings: (_) => const Text('settings body'),
+ },
+ );
+ await tester.pumpWidget(MaterialApp(home: shell));
+ await tester.pumpAndSettle();
+ }
+
+ Finder rail() => find.byType(NavigationRail);
+
+ Finder inRail(Finder finder) => find.descendant(of: rail(), matching: finder);
+
+ testWidgets('a wide window shows a labelled rail at the left edge, full '
+ 'height, with Settings pinned to its foot', (tester) async {
+ await pumpShell(tester, width: 1000);
+
+ expect(rail(), findsOneWidget);
+ expect(find.byType(FloatingDestinationBar), findsNothing);
+ for (final label in ['Pipelines', 'Runs', 'Chat', 'Search', 'Settings']) {
+ expect(inRail(find.text(label)), findsOneWidget, reason: label);
+ }
+ final railRect = tester.getRect(rail());
+ expect(railRect.left, 0);
+ expect(railRect.top, 0);
+ expect(railRect.height, 800);
+ expect(railRect.width, kNavigationRailWidth);
+
+ // Settings sits below every tab, at the bottom of the rail.
+ final settings = tester.getRect(
+ find.byKey(const ValueKey('shell.destination.settings')),
+ );
+ final runs = tester.getRect(
+ find.byKey(const ValueKey('shell.destination.runs')),
+ );
+ expect(settings.top, greaterThan(runs.bottom));
+ expect(settings.bottom, closeTo(railRect.bottom, 1));
+ });
+
+ testWidgets('the rail marks the selected tab and one tap selects another', (
+ tester,
+ ) async {
+ await pumpShell(tester, width: 1000);
+ expect(tester.widget(rail()).selectedIndex, 0);
+ expect(find.text('pipelines body'), findsOneWidget);
+
+ await tester.tap(find.byKey(const ValueKey('shell.destination.runs')));
+ await tester.pumpAndSettle();
+ expect(tester.widget(rail()).selectedIndex, 1);
+ expect(find.text('runs body'), findsOneWidget);
+ });
+
+ testWidgets('Settings opens from the rail foot as a page and no tab is '
+ 'selected meanwhile', (tester) async {
+ final semantics = tester.ensureSemantics();
+ await pumpShell(tester, width: 1000);
+
+ await tester.tap(find.byKey(const ValueKey('shell.destination.settings')));
+ await tester.pumpAndSettle();
+ expect(find.text('settings body'), findsOneWidget);
+ expect(tester.widget(rail()).selectedIndex, isNull);
+ expect(
+ tester
+ .getSemantics(inRail(find.bySemanticsLabel('Settings')))
+ .flagsCollection
+ .isSelected,
+ Tristate.isTrue,
+ );
+ // The page's own Back returns to Pipelines, the tab it belongs to.
+ await tester.tap(find.byKey(const ValueKey('shell.back')));
+ await tester.pumpAndSettle();
+ expect(tester.widget(rail()).selectedIndex, 0);
+ semantics.dispose();
+ });
+
+ testWidgets('the running count stays on the Runs item of the rail', (
+ tester,
+ ) async {
+ await pumpShell(tester, width: 1000, runningRunCount: 3);
+ final badge = find.byKey(const ValueKey('shell.badge.runs.running'));
+ expect(
+ find.descendant(of: badge, matching: find.text('3')),
+ findsOneWidget,
+ );
+ expect(
+ find.descendant(
+ of: find.byKey(const ValueKey('shell.destination.runs')),
+ matching: badge,
+ ),
+ findsOneWidget,
+ );
+ });
+
+ testWidgets('a list and its open item lay out to the right of the rail', (
+ tester,
+ ) async {
+ await pumpShell(tester, width: 1000, withPanes: true);
+ final list = tester.getRect(find.byKey(const ValueKey('list-detail-list')));
+ final body = tester.getRect(find.byKey(const ValueKey('list-detail-body')));
+ expect(list.left, closeTo(kNavigationRailSpace, 0.5));
+ expect(body.right, closeTo(1000, 0.5));
+ expect(body.left, greaterThan(list.right));
+ });
+
+ testWidgets('the rail appears from the threshold width, and below it the '
+ 'floating bar stays', (tester) async {
+ expect(
+ kNavigationRailMinWindowWidth,
+ kListDetailMinWidth + kNavigationRailSpace,
+ );
+
+ await pumpShell(tester, width: kNavigationRailMinWindowWidth - 1);
+ expect(rail(), findsNothing);
+ expect(find.byType(FloatingDestinationBar), findsOneWidget);
+
+ await pumpShell(tester, width: kNavigationRailMinWindowWidth);
+ expect(rail(), findsOneWidget);
+ expect(find.byType(FloatingDestinationBar), findsNothing);
+ });
+
+ testWidgets('at the threshold the body beside the rail meets the list-detail '
+ 'minimum, so the list sits beside its detail', (tester) async {
+ await pumpShell(
+ tester,
+ width: kNavigationRailMinWindowWidth,
+ withPanes: true,
+ );
+ final list = tester.getRect(find.byKey(const ValueKey('list-detail-list')));
+ final body = tester.getRect(find.byKey(const ValueKey('list-detail-body')));
+ // The list and detail fill the window beside the rail, at the split
+ // threshold: the list starts after the rail and the detail ends at the
+ // window's right edge, with the detail to the right of the list.
+ expect(list.left, closeTo(kNavigationRailSpace, 0.5));
+ expect(body.right, closeTo(kNavigationRailMinWindowWidth, 0.5));
+ expect(body.left, greaterThan(list.right));
+ });
+
+ testWidgets('phone and narrow windows keep the floating bar and no rail', (
+ tester,
+ ) async {
+ for (final width in [390.0, 640.0]) {
+ await pumpShell(tester, width: width);
+ expect(rail(), findsNothing, reason: '$width');
+ expect(
+ find.byKey(const ValueKey('shell.destination.settings')),
+ findsNothing,
+ reason: '$width',
+ );
+ expect(
+ find.byType(FloatingDestinationBar),
+ findsOneWidget,
+ reason: '$width',
+ );
+ }
+ });
+
+ testWidgets('floating windows keep to the right of the rail on a wide '
+ 'window, and use the whole window without one', (tester) async {
+ final manager = probeManager();
+ manager.open('probe', 'a');
+ Future pumpWindows(double width) async {
+ tester.view.physicalSize = Size(width, 800);
+ tester.view.devicePixelRatio = 1;
+ addTearDown(tester.view.reset);
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: Stack(
+ fit: StackFit.expand,
+ children: [
+ const SizedBox.expand(),
+ Positioned.fill(
+ child: WindowHost(manager: manager, reservesRail: true),
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ }
+
+ await pumpWindows(1280);
+ // The probe window opens at x=100; beside the rail it starts after it.
+ expect(
+ windowRect(tester, 'Probe a').left,
+ closeTo(100 + kNavigationRailSpace, 0.5),
+ );
+ await pumpWindows(500);
+ expect(windowRect(tester, 'Probe a').left, closeTo(100, 0.5));
+ });
+
+ testWidgets('crossing the rail threshold keeps the destination mounted and '
+ 'its state', (tester) async {
+ tester.view.physicalSize = Size(kNavigationRailMinWindowWidth - 1, 800);
+ tester.view.devicePixelRatio = 1;
+ addTearDown(tester.view.resetPhysicalSize);
+ addTearDown(tester.view.resetDevicePixelRatio);
+ await tester.pumpWidget(
+ MaterialApp(
+ home: AdaptiveShell(
+ destination: AppDestination.runs,
+ destinationBodies: {AppDestination.runs: (_) => const _Counter()},
+ ),
+ ),
+ );
+ await tester.pumpAndSettle();
+ await tester.tap(find.byKey(const ValueKey('counter.increment')));
+ await tester.pump();
+ final state = tester.state(find.byType(_Counter));
+
+ for (final width in [kNavigationRailMinWindowWidth, 390.0]) {
+ tester.view.physicalSize = Size(width, 800);
+ await tester.pumpAndSettle();
+ expect(
+ tester.state(find.byType(_Counter)),
+ same(state),
+ reason: '$width',
+ );
+ expect(find.text('count 1'), findsOneWidget, reason: '$width');
+ }
+ });
+}
+
+class _Counter extends StatefulWidget {
+ const _Counter();
+
+ @override
+ State<_Counter> createState() => _CounterState();
+}
+
+class _CounterState extends State<_Counter> {
+ int _count = 0;
+
+ @override
+ Widget build(BuildContext context) => Center(
+ child: TextButton(
+ key: const ValueKey('counter.increment'),
+ onPressed: () => setState(() => _count += 1),
+ child: Text('count $_count'),
+ ),
+ );
+}
diff --git a/app/test/shell/pane_bar_row_test.dart b/app/test/shell/pane_bar_row_test.dart
index 35955a87..f1387469 100644
--- a/app/test/shell/pane_bar_row_test.dart
+++ b/app/test/shell/pane_bar_row_test.dart
@@ -140,9 +140,9 @@ void main() {
expect(find.text('Its context'), findsOneWidget);
});
- testWidgets('1200: the item\'s tabs float at the bottom of its '
+ testWidgets('640: the item\'s tabs float at the bottom of its '
'pane, the shell\'s tab bar under the list', (tester) async {
- await setSize(tester, const Size(1200, 800));
+ await setSize(tester, const Size(640, 800));
await tester.pumpWidget(shell());
await tester.pump();
await tester.pump();
@@ -168,7 +168,7 @@ void main() {
expect(shellTabs.bottom, closeTo(800 - kFloatingBarMargin, 0.5));
expect(shellTabs.right, lessThanOrEqualTo(list.right));
expect(itemTabs.bottom, closeTo(800 - kFloatingBarMargin, 0.5));
- expect(itemTabs.right, closeTo(1200 - kFloatingBarMargin, 0.5));
+ expect(itemTabs.right, closeTo(640 - kFloatingBarMargin, 0.5));
expect(itemTabs.left, greaterThanOrEqualTo(body.left));
expect(itemTabs.overlaps(shellTabs), isFalse);
// The item's list starts below its bar and clears its tabs at rest.
diff --git a/app/test/shell/runs_pipelines_shortcut_test.dart b/app/test/shell/runs_pipelines_shortcut_test.dart
new file mode 100644
index 00000000..3bf2a038
--- /dev/null
+++ b/app/test/shell/runs_pipelines_shortcut_test.dart
@@ -0,0 +1,208 @@
+import 'package:flutter/foundation.dart';
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/shell/adaptive_shell.dart';
+import 'package:pipelines_app/shell/destination.dart';
+import 'package:pipelines_app/shell/shell_runs_pipelines_shortcut.dart';
+import 'package:pipelines_app/ui/input/keyboard_owner.dart';
+
+const _a = KeyDownEvent(
+ physicalKey: PhysicalKeyboardKey.keyA,
+ logicalKey: LogicalKeyboardKey.keyA,
+ timeStamp: Duration.zero,
+);
+
+void main() {
+ test('Ctrl+A matches only with Ctrl alone', () {
+ bool chord(Set held, [KeyEvent event = _a]) =>
+ shellRunsPipelinesShortcut(event, _FakeKeyboard(held));
+ expect(chord({}), isFalse);
+ expect(chord({LogicalKeyboardKey.controlLeft}), isTrue);
+ expect(chord({LogicalKeyboardKey.controlRight}), isTrue);
+ expect(
+ chord({LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.altLeft}),
+ isFalse,
+ );
+ expect(
+ chord({LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.shiftLeft}),
+ isFalse,
+ );
+ expect(
+ chord({LogicalKeyboardKey.controlLeft, LogicalKeyboardKey.metaLeft}),
+ isFalse,
+ );
+ expect(chord({LogicalKeyboardKey.altLeft}), isFalse);
+ expect(chord({LogicalKeyboardKey.metaLeft}), isFalse);
+ expect(
+ shellRunsPipelinesShortcut(
+ const KeyUpEvent(
+ physicalKey: PhysicalKeyboardKey.keyA,
+ logicalKey: LogicalKeyboardKey.keyA,
+ timeStamp: Duration.zero,
+ ),
+ _FakeKeyboard({LogicalKeyboardKey.controlLeft}),
+ ),
+ isFalse,
+ );
+ });
+
+ test('Runs goes to Pipelines; every other destination goes to Runs', () {
+ expect(
+ shellRunsPipelinesTarget(AppDestination.runs),
+ AppDestination.pipelines,
+ );
+ expect(
+ shellRunsPipelinesTarget(AppDestination.pipelines),
+ AppDestination.runs,
+ );
+ expect(shellRunsPipelinesTarget(AppDestination.chat), AppDestination.runs);
+ expect(
+ shellRunsPipelinesTarget(AppDestination.search),
+ AppDestination.runs,
+ );
+ expect(
+ shellRunsPipelinesTarget(AppDestination.settings),
+ AppDestination.runs,
+ );
+ });
+
+ testWidgets('Ctrl+A bounces Chat, Runs, Pipelines, Runs', (tester) async {
+ await _onAndroid(() async {
+ await tester.pumpWidget(
+ MaterialApp(
+ home: AdaptiveShell(
+ destinationBodies: {
+ for (final destination in shellTabDestinations)
+ destination: (_) => Text('${destination.name} body'),
+ },
+ ),
+ ),
+ );
+ expect(find.text('pipelines body'), isOnstage);
+
+ Future pressCtrl(LogicalKeyboardKey key) async {
+ await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft);
+ await tester.sendKeyEvent(key);
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.controlLeft);
+ await tester.pumpAndSettle();
+ }
+
+ // Reach Chat first with Ctrl+K, then start the Ctrl+A sequence.
+ await pressCtrl(LogicalKeyboardKey.keyK);
+ expect(find.text('chat body'), isOnstage);
+ expect(find.text('pipelines body'), findsNothing);
+
+ await pressCtrl(LogicalKeyboardKey.keyA);
+ expect(find.text('runs body'), isOnstage);
+ expect(find.text('chat body'), findsNothing);
+
+ await pressCtrl(LogicalKeyboardKey.keyA);
+ expect(find.text('pipelines body'), isOnstage);
+ expect(find.text('runs body'), findsNothing);
+
+ await pressCtrl(LogicalKeyboardKey.keyA);
+ expect(find.text('runs body'), isOnstage);
+ expect(find.text('pipelines body'), findsNothing);
+ expect(tester.takeException(), isNull);
+ });
+ });
+
+ testWidgets('Ctrl+A is left to a focused text field', (tester) async {
+ await _onAndroid(() async {
+ final field = TextEditingController(text: 'draft message');
+ final focus = FocusNode();
+ addTearDown(field.dispose);
+ addTearDown(focus.dispose);
+ await tester.pumpWidget(
+ MaterialApp(
+ home: AdaptiveShell(
+ destinationBodies: {
+ AppDestination.pipelines: (_) =>
+ TextField(controller: field, focusNode: focus),
+ AppDestination.runs: (_) => const Text('runs body'),
+ },
+ ),
+ ),
+ );
+ focus.requestFocus();
+ await tester.pump();
+ expect(focus.hasPrimaryFocus, isTrue);
+
+ await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft);
+ await tester.sendKeyEvent(LogicalKeyboardKey.keyA);
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.controlLeft);
+ await tester.pumpAndSettle();
+
+ // Destination unchanged; the field took the chord (select all on this
+ // platform), so the text is still there and fully selected.
+ expect(find.text('runs body'), findsNothing);
+ expect(field.text, 'draft message');
+ expect(field.selection.baseOffset, 0);
+ expect(field.selection.extentOffset, field.text.length);
+ expect(tester.takeException(), isNull);
+ });
+ });
+
+ testWidgets('Ctrl+A is left to the terminal while it has focus', (
+ tester,
+ ) async {
+ await _onAndroid(() async {
+ final terminal = FocusNode();
+ addTearDown(terminal.dispose);
+ final received = [];
+ await tester.pumpWidget(
+ MaterialApp(
+ home: AdaptiveShell(
+ destinationBodies: {
+ AppDestination.pipelines: (_) => TypingSurface(
+ child: Focus(
+ focusNode: terminal,
+ onKeyEvent: (node, event) {
+ if (event.logicalKey == LogicalKeyboardKey.keyA) {
+ received.add(event);
+ }
+ return KeyEventResult.ignored;
+ },
+ child: const Text('terminal'),
+ ),
+ ),
+ AppDestination.runs: (_) => const Text('runs body'),
+ },
+ ),
+ ),
+ );
+ terminal.requestFocus();
+ await tester.pump();
+
+ await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft);
+ await tester.sendKeyEvent(LogicalKeyboardKey.keyA);
+ await tester.sendKeyUpEvent(LogicalKeyboardKey.controlLeft);
+ await tester.pumpAndSettle();
+
+ expect(find.text('runs body'), findsNothing);
+ expect(find.text('terminal'), isOnstage);
+ expect(received.whereType(), hasLength(1));
+ expect(tester.takeException(), isNull);
+ });
+ });
+}
+
+/// Runs [body] with the platform pinned to Android, so Ctrl+A in a text field
+/// means select all everywhere. flutter_test requires the debug override to be
+/// cleared before the test body returns, hence the `finally`.
+Future _onAndroid(Future Function() body) async {
+ debugDefaultTargetPlatformOverride = TargetPlatform.android;
+ try {
+ await body();
+ } finally {
+ debugDefaultTargetPlatformOverride = null;
+ }
+}
+
+class _FakeKeyboard extends HardwareKeyboard {
+ _FakeKeyboard(this.pressed);
+ final Set pressed;
+ @override
+ bool isLogicalKeyPressed(LogicalKeyboardKey key) => pressed.contains(key);
+}
diff --git a/app/test/shell/split_destination_bar_test.dart b/app/test/shell/split_destination_bar_test.dart
index 5da220a7..c0e7c2e9 100644
--- a/app/test/shell/split_destination_bar_test.dart
+++ b/app/test/shell/split_destination_bar_test.dart
@@ -106,7 +106,7 @@ void main() {
.first,
);
- for (final width in [1200.0, 1600.0]) {
+ for (final width in [600.0, 640.0]) {
testWidgets('$width split: the destination bar sits under the '
'list and the composer at the detail\'s bottom edge', (tester) async {
await setSize(tester, Size(width, 800));
@@ -211,11 +211,12 @@ void main() {
});
}
- testWidgets('1200 split: the bar follows a dragged list width', (
+ testWidgets('640 split: the bar follows a dragged list width', (
tester,
) async {
- await setSize(tester, const Size(1200, 800));
- for (final width in [300.0, 520.0]) {
+ await setSize(tester, const Size(640, 800));
+ // Within a 640 window's list bounds (at most 0.6 of it, less the body).
+ for (final width in [260.0, 300.0]) {
final store = MemoryListPaneWidthStore({'chat': width});
await tester.pumpWidget(
KeyedSubtree(
@@ -235,26 +236,26 @@ void main() {
}
});
- testWidgets('1200 Settings: a page without a list keeps the bar '
+ testWidgets('640 Settings: a page without a list keeps the bar '
'at the right edge', (tester) async {
- await setSize(tester, const Size(1200, 800));
+ await setSize(tester, const Size(640, 800));
await tester.pumpWidget(shell(destination: AppDestination.settings));
await tester.pump();
final pill = destinationPill(tester);
- expect(pill.right, closeTo(1200 - kFloatingBarMargin, 0.5));
+ expect(pill.right, closeTo(640 - kFloatingBarMargin, 0.5));
});
- testWidgets('1200 unsplit: the bar stays under the list column', (
+ testWidgets('640 unsplit: the bar stays under the list column', (
tester,
) async {
- await setSize(tester, const Size(1200, 800));
+ await setSize(tester, const Size(640, 800));
await tester.pumpWidget(shell(split: false));
await tester.pump();
final pill = destinationPill(tester);
// Same place as beside an open item (Search has no split), so opening
// or closing an item never moves the bar across the window.
expect(pill.left, closeTo(kFloatingBarMargin, 0.5));
- expect(pill.width, lessThan(1200 * 0.6));
+ expect(pill.width, lessThan(640 * 0.6));
});
testWidgets('390: the bar hugs its tabs at the phone\'s bottom '
@@ -277,7 +278,7 @@ void main() {
expect(pill.right, closeTo(390 - kFloatingBarMargin, 0.5));
});
- for (final width in [600.0, 840.0]) {
+ for (final width in [600.0, 640.0]) {
testWidgets('$width split at 2x: the bar fits the list pane and '
'the item tabs the detail, without overflow', (tester) async {
await setSize(tester, Size(width, 800));
diff --git a/app/test/shell/split_detail_pages_test.dart b/app/test/shell/split_detail_pages_test.dart
index cef81444..5ed854c6 100644
--- a/app/test/shell/split_detail_pages_test.dart
+++ b/app/test/shell/split_detail_pages_test.dart
@@ -36,7 +36,7 @@ void main() {
);
Future pumpSplitRun(WidgetTester tester) async {
- tester.view.physicalSize = const Size(1200, 800);
+ tester.view.physicalSize = const Size(640, 800);
tester.view.devicePixelRatio = 1;
addTearDown(tester.view.reset);
final gateway = RunDetailFakeGateway(visitRunFixture());
@@ -71,7 +71,7 @@ void main() {
await tester.pumpAndSettle();
}
- testWidgets('1200: run tabs float at the pane\'s bottom beside the '
+ testWidgets('640: run tabs float at the pane\'s bottom beside the '
'shell bar under the list, and the stage page opens in the pane', (
tester,
) async {
@@ -84,7 +84,7 @@ void main() {
final runTabs = pillOf(tester, find.byKey(const Key('run-detail-tabs')));
expect(runTabs.left, greaterThanOrEqualTo(body.left));
- expect(runTabs.right, closeTo(1200 - kFloatingBarMargin, 0.5));
+ expect(runTabs.right, closeTo(640 - kFloatingBarMargin, 0.5));
expect(runTabs.overlaps(main), isFalse);
expect(runTabs.bottom, closeTo(800 - kFloatingBarMargin, 0.5));
diff --git a/app/test/shell/split_status_bar_test.dart b/app/test/shell/split_status_bar_test.dart
index 382b4fc5..40432fd3 100644
--- a/app/test/shell/split_status_bar_test.dart
+++ b/app/test/shell/split_status_bar_test.dart
@@ -158,7 +158,7 @@ void main() {
testWidgets('split: the item tabs sit at the bottom right of the '
'detail pane, the shell tab bar under the list', (tester) async {
// A gesture-navigation inset as on the unfolded foldable.
- await setUp(tester, const Size(1200, 800), bottom: 24);
+ await setUp(tester, const Size(640, 800), bottom: 24);
await tester.pumpWidget(shell(tabbedItem()));
await tester.pump();
await tester.pump();
@@ -188,7 +188,7 @@ void main() {
expect(shellTabs.bottom, closeTo(800 - 24, 0.5));
expect(shellTabs.right, lessThanOrEqualTo(listPane.right));
expect(tabs.bottom, closeTo(800 - 24, 0.5));
- expect(tabs.right, closeTo(1200 - kFloatingBarMargin, 0.5));
+ expect(tabs.right, closeTo(640 - kFloatingBarMargin, 0.5));
expect(shellTabs.overlaps(tabs), isFalse);
// The item's list clears its tabs at rest.
final list = tester.element(find.byKey(const Key('item-list')));
diff --git a/app/test/shell/windows/window_host_test.dart b/app/test/shell/windows/window_host_test.dart
index 75e5574e..a16c6902 100644
--- a/app/test/shell/windows/window_host_test.dart
+++ b/app/test/shell/windows/window_host_test.dart
@@ -25,9 +25,11 @@ void main() {
const Rect.fromLTWH(100, 80, 360, 420),
);
expect(find.byTooltip('Probe action'), findsOneWidget);
- for (final tip in ['Minimise', 'Maximise', 'Close']) {
+ for (final tip in ['Minimise', 'Maximise']) {
expect(find.byTooltip(tip), findsOneWidget);
}
+ // There is no separate Minimise button: the X is the one minimise.
+ expect(find.byTooltip('Close'), findsNothing);
expect(find.text('sheet').hitTestable(), findsOneWidget);
// The title bar, the content and the app behind all keep their
// semantics (a page route's barrier hides what is behind it).
@@ -172,14 +174,30 @@ void main() {
expect(find.text('typed'), findsOneWidget);
});
- testWidgets('X closes the window', (tester) async {
+ testWidgets('X minimises the window and never closes it', (tester) async {
final entry = manager.open('probe', 'a');
await pumpProbe(tester, manager);
- await tester.tap(find.byTooltip('Close'));
+ await tester.enterText(find.byKey(const ValueKey('a-field')), 'kept');
+ final state = tester.state(find.byType(ProbeContent));
+ await tester.tap(find.byTooltip('Minimise'));
await tester.pumpAndSettle();
- expect(manager.windows, isEmpty);
- expect(find.byType(ProbeContent, skipOffstage: false), findsNothing);
- expect((manager.kinds['probe']! as ProbeWindowKind).closed_, [entry.id]);
+ expect(manager.windows.single.id, entry.id);
+ expect(manager.byId(entry.id)!.minimized, isTrue);
+ expect(find.text('Probe a').hitTestable(), findsNothing);
+ // Not a close: the kind's closed hook does not run, and the content
+ // stays alive with its state.
+ expect((manager.kinds['probe']! as ProbeWindowKind).closed_, isEmpty);
+ expect(
+ tester.state(
+ find.byType(ProbeContent, skipOffstage: false),
+ ),
+ same(state),
+ );
+ // Listed and brought back by the group, as Minimise always was.
+ manager.toggleGroup('probe');
+ await tester.pumpAndSettle();
+ expect(find.text('Probe a').hitTestable(), findsOneWidget);
+ expect(find.text('kept'), findsOneWidget);
});
testWidgets('pressing a window brings it to the top and keeps both alive', (
diff --git a/app/test/shell/windows/window_layering_test.dart b/app/test/shell/windows/window_layering_test.dart
index ff2dbac5..a60d21e6 100644
--- a/app/test/shell/windows/window_layering_test.dart
+++ b/app/test/shell/windows/window_layering_test.dart
@@ -209,14 +209,17 @@ void main() {
probeTooltipColor,
);
- await mouse.moveTo(tester.getCenter(find.byTooltip('Close').last));
+ await mouse.moveTo(tester.getCenter(find.byTooltip('Minimise').last));
await tester.pumpAndSettle(const Duration(seconds: 1));
- expect(find.text('Close'), findsOneWidget);
+ expect(find.text('Minimise'), findsOneWidget);
// Not clipped to the window: tooltips paint in an overlay as large
// as the app.
final overlay = tester.renderObject(
find
- .ancestor(of: find.text('Close'), matching: find.byType(Overlay))
+ .ancestor(
+ of: find.text('Minimise'),
+ matching: find.byType(Overlay),
+ )
.first,
);
expect(overlay.size, const Size(1280, 800));
diff --git a/app/test/ui/motion/container_transform_back_start_test.dart b/app/test/ui/motion/container_transform_back_start_test.dart
new file mode 100644
index 00000000..455c8c41
--- /dev/null
+++ b/app/test/ui/motion/container_transform_back_start_test.dart
@@ -0,0 +1,141 @@
+import 'dart:async';
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:pipelines_app/shell/destination.dart';
+import 'package:pipelines_app/shell/detail_page.dart';
+import 'package:pipelines_app/shell/shell_bar.dart';
+import 'package:pipelines_app/ui/motion/container_transform_flight.dart';
+import 'package:pipelines_app/ui/motion/container_transform_source.dart';
+import 'package:pipelines_app/ui/motion/motion.dart';
+
+const _screen = Size(390, 844);
+
+/// A phone-style owner: its selected row opens a detail page that grows from
+/// the row, as the chat screen's page does.
+class _Owner extends StatefulWidget {
+ const _Owner({required this.selection, required this.sources});
+
+ final ValueNotifier