From a8158b1ef5e7f0ad9bbc940ee7521cc5d1a49d4b Mon Sep 17 00:00:00 2001
From: archipelago <archipelago@localhost>
Date: Thu, 23 Apr 2026 05:20:15 -0400
Subject: [PATCH] fix(ui): single-button lifecycle control with transitional
 labels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The app card and details view previously used a pair of Start/Stop
buttons whose labels were driven off isAppLoading(), a client-side
"I just clicked the button" flag. When the backend's graceful stop
took longer than the RPC round-trip (up to 600s on bitcoin-core),
the flag cleared while the container was still shutting down, the
UI flipped back to "Running" as soon as the next 10s scan saw the
still-alive container, and the user had no indication the stop was
still in flight.

Now that the backend flips PackageState to Stopping / Starting /
Restarting / Installing / Updating / Removing for the duration of
each lifecycle operation and the scan loop preserves those states,
the UI can drive its label off the container state itself. A single
full-width primary button replaces the Start/Stop pair. Its label,
color, and disabled state come from getAppVisualState(), which
collapses resting states (exited/created/paused/installed) into
"stopped" and passes transitional states through untouched.

Changes:

- container-client.ts: widen ContainerStatus.state union to include
  the six transitional variants plus "installed". Add
  restartContainer() calling the new container-restart RPC.
- stores/container.ts: add getAppVisualState() computed and the
  restartContainer() action.
- ContainerApps.vue: single primary button (Start / Stop / Starting
  / Stopping / Restarting etc.) plus a separate circular Restart
  button visible only when running. Critically, handleStartApp and
  handleStopApp now route through store.startContainer and
  stopContainer (which call container-start / container-stop, the
  async RPCs) instead of the legacy synchronous bundled-app-start /
  bundled-app-stop path. Transitional-state polling widened from
  just "created" to the full set of transitional variants.
- ContainerAppDetails.vue: same single-button pattern, Restart
  button now calls container-restart instead of the old
  stop-sleep-start sequence, added 2s polling interval for
  transitional states.
- components/ContainerStatus.vue: widen state prop to match the
  shared union, render transitional labels with a trailing ellipsis
  and a yellow dot.

No new tests — this is presentation logic. Manual verification on
.228 will confirm the end-to-end async path: click Stop on LND,
button becomes "Stopping" in under a second, stays that way for
roughly 5 minutes, then flips to "Start" with a grey dot. The UI
must never revert to "Running" mid-stop.
---
 neode-ui/src/api/container-client.ts        |  25 ++-
 neode-ui/src/components/ContainerStatus.vue |  43 +++-
 neode-ui/src/stores/container.ts            |  57 ++++++
 neode-ui/src/views/ContainerAppDetails.vue  | 130 ++++++++++--
 neode-ui/src/views/ContainerApps.vue        | 208 +++++++++++++-------
 5 files changed, 367 insertions(+), 96 deletions(-)

diff --git a/neode-ui/src/api/container-client.ts b/neode-ui/src/api/container-client.ts
index 83547db0..82ba0af9 100644
--- a/neode-ui/src/api/container-client.ts
+++ b/neode-ui/src/api/container-client.ts
@@ -6,7 +6,20 @@ import { rpcClient } from './rpc-client'
 export interface ContainerStatus {
   id: string
   name: string
-  state: 'created' | 'running' | 'stopped' | 'exited' | 'paused' | 'unknown'
+  state:
+    | 'created'
+    | 'running'
+    | 'stopped'
+    | 'exited'
+    | 'paused'
+    | 'unknown'
+    | 'stopping'
+    | 'starting'
+    | 'restarting'
+    | 'installing'
+    | 'updating'
+    | 'removing'
+    | 'installed'
   image: string
   created: string
   ports: string[]
@@ -60,6 +73,16 @@ export const containerClient = {
     })
   },
 
+  /**
+   * Restart a container (async; returns immediately with restarting state)
+   */
+  async restartContainer(appId: string): Promise<void> {
+    return rpcClient.call<void>({
+      method: 'container-restart',
+      params: { app_id: appId },
+    })
+  },
+
   /**
    * Remove a container
    */
diff --git a/neode-ui/src/components/ContainerStatus.vue b/neode-ui/src/components/ContainerStatus.vue
index 1ef698e2..ab921507 100644
--- a/neode-ui/src/components/ContainerStatus.vue
+++ b/neode-ui/src/components/ContainerStatus.vue
@@ -33,7 +33,20 @@
 import { computed } from 'vue'
 
 interface Props {
-  state: 'created' | 'running' | 'stopped' | 'exited' | 'paused' | 'unknown'
+  state:
+    | 'created'
+    | 'running'
+    | 'stopped'
+    | 'exited'
+    | 'paused'
+    | 'unknown'
+    | 'stopping'
+    | 'starting'
+    | 'restarting'
+    | 'installing'
+    | 'updating'
+    | 'removing'
+    | 'installed'
   health?: 'healthy' | 'unhealthy' | 'unknown' | 'starting'
 }
 
@@ -49,8 +62,15 @@ const statusClass = computed(() => {
       return 'bg-green-400'
     case 'stopped':
     case 'exited':
+    case 'installed':
       return 'bg-gray-400'
     case 'paused':
+    case 'starting':
+    case 'stopping':
+    case 'restarting':
+    case 'installing':
+    case 'updating':
+    case 'removing':
       return 'bg-yellow-400'
     default:
       return 'bg-red-400'
@@ -63,8 +83,15 @@ const textClass = computed(() => {
       return 'text-green-400'
     case 'stopped':
     case 'exited':
+    case 'installed':
       return 'text-gray-400'
     case 'paused':
+    case 'starting':
+    case 'stopping':
+    case 'restarting':
+    case 'installing':
+    case 'updating':
+    case 'removing':
       return 'text-yellow-400'
     default:
       return 'text-red-400'
@@ -83,6 +110,20 @@ const statusText = computed(() => {
       return 'Paused'
     case 'created':
       return 'Created'
+    case 'installed':
+      return 'Installed'
+    case 'starting':
+      return 'Starting…'
+    case 'stopping':
+      return 'Stopping…'
+    case 'restarting':
+      return 'Restarting…'
+    case 'installing':
+      return 'Installing…'
+    case 'updating':
+      return 'Updating…'
+    case 'removing':
+      return 'Removing…'
     default:
       return 'Unknown'
   }
diff --git a/neode-ui/src/stores/container.ts b/neode-ui/src/stores/container.ts
index 584f47a2..61f6f9be 100644
--- a/neode-ui/src/stores/container.ts
+++ b/neode-ui/src/stores/container.ts
@@ -141,6 +141,46 @@ export const useContainerStore = defineStore('container', () => {
     return container.state
   })
 
+  // Get visual state for UI — collapses backend states into the small set the
+  // single-button component needs. Transitional states (stopping/starting/
+  // restarting/installing/updating/removing) pass through; resting states
+  // (exited/created/paused/installed) collapse to 'stopped' or 'running' so
+  // the button logic can stay simple.
+  type VisualState =
+    | 'not-installed'
+    | 'running'
+    | 'stopped'
+    | 'stopping'
+    | 'starting'
+    | 'restarting'
+    | 'installing'
+    | 'updating'
+    | 'removing'
+    | 'unknown'
+  const getAppVisualState = computed(() => (appId: string): VisualState => {
+    const container = getContainerForApp.value(appId)
+    if (!container) return 'not-installed'
+    switch (container.state) {
+      case 'running':
+        return 'running'
+      case 'stopped':
+      case 'exited':
+      case 'created':
+      case 'paused':
+      case 'installed':
+        return 'stopped'
+      case 'stopping':
+      case 'starting':
+      case 'restarting':
+      case 'installing':
+      case 'updating':
+      case 'removing':
+        return container.state
+      default:
+        return 'unknown'
+    }
+  })
+
   // Get enriched bundled apps with runtime data (like lan_address)
   const enrichedBundledApps = computed(() => {
     return BUNDLED_APPS.map(app => {
@@ -218,6 +258,21 @@ export const useContainerStore = defineStore('container', () => {
     }
   }
 
+  async function restartContainer(appId: string) {
+    loadingApps.value.add(appId)
+    error.value = null
+    try {
+      await containerClient.restartContainer(appId)
+      await fetchContainers()
+      await fetchHealthStatus()
+    } catch (e) {
+      error.value = e instanceof Error ? e.message : 'Failed to restart container'
+      throw e
+    } finally {
+      loadingApps.value.delete(appId)
+    }
+  }
+
   // Start a bundled app (creates and starts container)
   async function startBundledApp(app: BundledApp) {
     loadingApps.value.add(app.id)
@@ -296,6 +351,7 @@ export const useContainerStore = defineStore('container', () => {
     getContainerForApp,
     isAppLoading,
     getAppState,
+    getAppVisualState,
     enrichedBundledApps,
     // Actions
     fetchContainers,
@@ -303,6 +359,7 @@ export const useContainerStore = defineStore('container', () => {
     installApp,
     startContainer,
     stopContainer,
+    restartContainer,
     removeContainer,
     getContainerLogs,
     getContainerStatus,
diff --git a/neode-ui/src/views/ContainerAppDetails.vue b/neode-ui/src/views/ContainerAppDetails.vue
index 0135f11a..906942b1 100644
--- a/neode-ui/src/views/ContainerAppDetails.vue
+++ b/neode-ui/src/views/ContainerAppDetails.vue
@@ -66,32 +66,30 @@
       <div class="glass-card p-6">
         <h2 class="text-xl font-semibold text-white mb-4">{{ t('containerDetails.actions') }}</h2>
         <div class="flex gap-4">
+          <!-- Single primary button: Start when stopped, Stop when running,
+               transitional label + spinner while stopping/starting/restarting. -->
           <button
-            v-if="container.state !== 'running'"
-            @click="handleStart"
-            :disabled="actionLoading"
-            class="px-6 py-3 glass-button rounded-lg font-medium text-white/90 hover:text-white transition-colors disabled:opacity-50"
+            :disabled="isPrimaryDisabled"
+            @click="handlePrimary"
+            :class="primaryButtonClass"
+            class="px-6 py-3 rounded-lg font-medium text-white transition-colors disabled:opacity-60 disabled:cursor-not-allowed flex items-center gap-2"
           >
-            {{ t('containerDetails.startContainer') }}
-          </button>
-          <button
-            v-else
-            @click="handleStop"
-            :disabled="actionLoading"
-            class="px-6 py-3 glass-button rounded-lg font-medium text-white/90 hover:text-white transition-colors disabled:opacity-50"
-          >
-            {{ t('containerDetails.stopContainer') }}
+            <svg v-if="isTransitional" class="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
+              <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+              <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+            </svg>
+            <span>{{ primaryButtonLabel }}</span>
           </button>
           <button
             @click="handleRestart"
-            :disabled="actionLoading || container.state !== 'running'"
+            :disabled="actionLoading || isTransitional || container.state !== 'running'"
             class="px-6 py-3 glass-button rounded-lg font-medium text-white/90 hover:text-white transition-colors disabled:opacity-50"
           >
             {{ t('common.restart') }}
           </button>
           <button
             @click="handleRemove"
-            :disabled="actionLoading"
+            :disabled="actionLoading || isTransitional"
             class="px-6 py-3 glass-button rounded-lg font-medium text-red-400/90 hover:text-red-400 transition-colors disabled:opacity-50"
           >
             {{ t('common.remove') }}
@@ -131,14 +129,27 @@
 </template>
 
 <script setup lang="ts">
-import { ref, computed, onMounted } from 'vue'
+import { ref, computed, onMounted, onUnmounted } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useI18n } from 'vue-i18n'
 import { useContainerStore } from '@/stores/container'
 import { type ContainerStatus as ContainerStatusData } from '@/api/container-client'
 import ContainerStatus from '@/components/ContainerStatus.vue'
 
-type ContainerStateValue = 'created' | 'running' | 'stopped' | 'exited' | 'paused' | 'unknown'
+type ContainerStateValue =
+  | 'created'
+  | 'running'
+  | 'stopped'
+  | 'exited'
+  | 'paused'
+  | 'unknown'
+  | 'stopping'
+  | 'starting'
+  | 'restarting'
+  | 'installing'
+  | 'updating'
+  | 'removing'
+  | 'installed'
 type HealthStatusValue = 'healthy' | 'unhealthy' | 'unknown' | 'starting'
 
 const route = useRoute()
@@ -229,9 +240,9 @@ async function handleStop() {
 async function handleRestart() {
   actionLoading.value = true
   try {
-    await store.stopContainer(appId.value)
-    await new Promise(resolve => setTimeout(resolve, 1000))
-    await store.startContainer(appId.value)
+    // Use the async container-restart RPC (returns immediately, backend
+    // flips state to Restarting and spawns the stop+start sequence).
+    await store.restartContainer(appId.value)
     await loadContainer()
     await loadHealthStatus()
   } catch (e) {
@@ -241,6 +252,85 @@ async function handleRestart() {
   }
 }
 
+// Single-button state helpers mirroring ContainerApps.vue — driven off the
+// backend state so transitional labels stay accurate across the 5–600s
+// graceful-stop window.
+const isTransitional = computed(() => {
+  const s = container.value?.state
+  return (
+    s === 'stopping' ||
+    s === 'starting' ||
+    s === 'restarting' ||
+    s === 'installing' ||
+    s === 'updating' ||
+    s === 'removing'
+  )
+})
+
+const isPrimaryDisabled = computed(() => actionLoading.value || isTransitional.value)
+
+const primaryButtonLabel = computed(() => {
+  const s = container.value?.state
+  switch (s) {
+    case 'running':
+      return t('containerDetails.stopContainer')
+    case 'stopping':
+      return 'Stopping…'
+    case 'starting':
+      return 'Starting…'
+    case 'restarting':
+      return 'Restarting…'
+    case 'installing':
+      return 'Installing…'
+    case 'updating':
+      return 'Updating…'
+    case 'removing':
+      return 'Removing…'
+    default:
+      return t('containerDetails.startContainer')
+  }
+})
+
+const primaryButtonClass = computed(() => {
+  const s = container.value?.state
+  if (s === 'running') {
+    return 'glass-button hover:text-white text-white/90'
+  }
+  if (isTransitional.value) {
+    return 'bg-yellow-700/40 text-yellow-200'
+  }
+  return 'bg-green-600 hover:bg-green-500'
+})
+
+async function handlePrimary() {
+  const s = container.value?.state
+  if (s === 'running') {
+    return handleStop()
+  }
+  if (!isTransitional.value) {
+    return handleStart()
+  }
+}
+
+// Poll every 2s while a transition is in flight so the label updates
+// without needing a manual refresh.
+let transitionalPollInterval: ReturnType<typeof setInterval> | null = null
+onMounted(() => {
+  transitionalPollInterval = setInterval(async () => {
+    if (isTransitional.value) {
+      try {
+        await loadContainer()
+      } catch {
+        // ignore transient poll errors
+      }
+    }
+  }, 2000)
+})
+
+onUnmounted(() => {
+  if (transitionalPollInterval) clearInterval(transitionalPollInterval)
+})
+
 async function handleRemove() {
   if (!confirm(t('apps.uninstallConfirm', { name: appName.value }))) {
     return
diff --git a/neode-ui/src/views/ContainerApps.vue b/neode-ui/src/views/ContainerApps.vue
index 9f80d175..85588b28 100644
--- a/neode-ui/src/views/ContainerApps.vue
+++ b/neode-ui/src/views/ContainerApps.vue
@@ -80,71 +80,48 @@
 
         <!-- Action Buttons -->
         <div class="flex gap-2">
-          <!-- Not installed: Start button -->
+          <!-- Single primary button whose label + action depend on visual state.
+               Transitional states (stopping/starting/restarting/installing/
+               updating/removing) show a spinner and are disabled. -->
           <button
-            v-if="store.getAppState(app.id) === 'not-installed'"
-            @click="handleStartApp(app)"
-            :disabled="store.isAppLoading(app.id)"
-            class="flex-1 px-4 py-2 bg-green-600 hover:bg-green-500 disabled:bg-green-800 disabled:cursor-not-allowed rounded text-sm font-medium text-white transition-colors flex items-center justify-center gap-2"
+            :disabled="isPrimaryDisabled(app.id)"
+            @click="handlePrimary(app)"
+            :class="primaryButtonClass(app.id)"
+            class="flex-1 px-4 py-2 rounded text-sm font-medium text-white transition-colors flex items-center justify-center gap-2 disabled:cursor-not-allowed"
           >
-            <svg v-if="store.isAppLoading(app.id)" class="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
+            <svg v-if="isTransitional(app.id)" class="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
               <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
               <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
             </svg>
-            <span>{{ store.isAppLoading(app.id) ? 'Starting...' : 'Start' }}</span>
+            <span>{{ primaryButtonLabel(app.id) }}</span>
           </button>
 
-          <!-- Stopped: Start button -->
+          <!-- Restart button: only visible when running, hidden during transitions -->
           <button
-            v-else-if="store.getAppState(app.id) === 'stopped' || store.getAppState(app.id) === 'exited'"
-            @click="handleStartApp(app)"
+            v-if="store.getAppVisualState(app.id) === 'running'"
+            @click="handleRestartApp(app.id)"
             :disabled="store.isAppLoading(app.id)"
-            class="flex-1 px-4 py-2 bg-green-600 hover:bg-green-500 disabled:bg-green-800 disabled:cursor-not-allowed rounded text-sm font-medium text-white transition-colors flex items-center justify-center gap-2"
+            class="px-4 py-2 glass-button rounded text-sm font-medium text-white/90 hover:text-white disabled:cursor-not-allowed transition-colors"
+            :title="'Restart ' + app.name"
           >
-            <svg v-if="store.isAppLoading(app.id)" class="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
-              <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
-              <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+            <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M4 4v5h.582m15.356 2A8.001 8.001 0 004.582 9m0 0H9m11 11v-5h-.581m0 0a8.003 8.003 0 01-15.357-2m15.357 2H15" />
             </svg>
-            <span>{{ store.isAppLoading(app.id) ? 'Starting...' : 'Start' }}</span>
           </button>
 
-          <!-- Starting (created): show progress, no Launch yet -->
-          <div
-            v-else-if="store.getAppState(app.id) === 'created'"
-            class="flex-1 flex items-center justify-center gap-2 px-4 py-2 text-white/70 text-sm"
+          <!-- Launch button: only when running -->
+          <button
+            v-if="store.getAppVisualState(app.id) === 'running'"
+            type="button"
+            data-controller-launch-btn
+            class="px-4 py-2 bg-blue-600 hover:bg-blue-500 rounded text-sm font-medium text-white transition-colors flex items-center gap-2"
+            @click="launchApp(app)"
           >
-            <svg class="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
-              <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
-              <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+            <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" />
             </svg>
-            <span>Starting…</span>
-          </div>
-
-          <!-- Running: Stop and Launch buttons -->
-          <template v-else-if="store.getAppState(app.id) === 'running'">
-            <button
-              @click="handleStopApp(app.id)"
-              :disabled="store.isAppLoading(app.id)"
-              class="flex-1 px-4 py-2 glass-button rounded text-sm font-medium text-white/90 hover:text-white disabled:cursor-not-allowed transition-colors flex items-center justify-center gap-2"
-            >
-              <svg v-if="store.isAppLoading(app.id)" class="w-4 h-4 animate-spin" fill="none" viewBox="0 0 24 24">
-                <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
-                <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
-              </svg>
-              <span>{{ store.isAppLoading(app.id) ? 'Stopping...' : 'Stop' }}</span>
-            </button>
-            <button
-              type="button"
-              data-controller-launch-btn
-              class="px-4 py-2 bg-blue-600 hover:bg-blue-500 rounded text-sm font-medium text-white transition-colors flex items-center gap-2"
-              @click="launchApp(app)"
-            >
-              <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">
-                <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" />
-              </svg>
-              Launch
-            </button>
-          </template>
+            Launch
+          </button>
         </div>
       </div>
 
@@ -234,10 +211,11 @@ onMounted(async () => {
     }
   }, 10000)
 
-  // When any bundled app is in 'created' (starting), poll every 2s so state updates to running
+  // When any bundled app is transitional (stopping/starting/restarting/etc),
+  // poll every 2s so state updates flow through quickly.
   startingPollInterval = setInterval(async () => {
-    const anyStarting = bundledApps.value.some((app) => store.getAppState(app.id) === 'created')
-    if (anyStarting) {
+    const anyTransitional = bundledApps.value.some((app) => isTransitional(app.id))
+    if (anyTransitional) {
       try {
         await store.fetchContainers()
         await store.fetchHealthStatus()
@@ -273,17 +251,18 @@ function extractAppName(containerName: string): string {
 }
 
 function getStatusBadgeClass(appId: string): string {
-  if (store.isAppLoading(appId)) {
-    return 'bg-yellow-500/20 text-yellow-400'
-  }
-  const state = store.getAppState(appId)
-  switch (state) {
+  const vs = store.getAppVisualState(appId)
+  switch (vs) {
     case 'running':
       return 'bg-green-500/20 text-green-400'
     case 'stopped':
-    case 'exited':
       return 'bg-gray-500/20 text-gray-400'
-    case 'created':
+    case 'starting':
+    case 'stopping':
+    case 'restarting':
+    case 'installing':
+    case 'updating':
+    case 'removing':
       return 'bg-yellow-500/20 text-yellow-400'
     case 'not-installed':
     default:
@@ -292,39 +271,98 @@ function getStatusBadgeClass(appId: string): string {
 }
 
 function getStatusDotClass(appId: string): string {
-  const state = store.getAppState(appId)
-  switch (state) {
+  const vs = store.getAppVisualState(appId)
+  switch (vs) {
     case 'running':
       return 'bg-green-400'
     case 'stopped':
-    case 'exited':
       return 'bg-gray-400'
     case 'not-installed':
-    default:
       return 'bg-blue-400'
+    default:
+      return 'bg-yellow-400'
   }
 }
 
 function getStatusText(appId: string): string {
-  if (store.isAppLoading(appId)) {
-    return 'Loading...'
-  }
-  const state = store.getAppState(appId)
-  switch (state) {
+  const vs = store.getAppVisualState(appId)
+  switch (vs) {
     case 'running':
       return 'Running'
     case 'stopped':
-    case 'exited':
       return 'Stopped'
     case 'not-installed':
       return 'Ready to Start'
-    case 'created':
+    case 'starting':
       return 'Starting'
+    case 'stopping':
+      return 'Stopping'
+    case 'restarting':
+      return 'Restarting'
+    case 'installing':
+      return 'Installing'
+    case 'updating':
+      return 'Updating'
+    case 'removing':
+      return 'Removing'
     default:
-      return state
+      return 'Unknown'
   }
 }
 
+function isTransitional(appId: string): boolean {
+  const vs = store.getAppVisualState(appId)
+  return (
+    vs === 'starting' ||
+    vs === 'stopping' ||
+    vs === 'restarting' ||
+    vs === 'installing' ||
+    vs === 'updating' ||
+    vs === 'removing'
+  )
+}
+
+function isPrimaryDisabled(appId: string): boolean {
+  return isTransitional(appId) || store.isAppLoading(appId)
+}
+
+function primaryButtonLabel(appId: string): string {
+  const vs = store.getAppVisualState(appId)
+  switch (vs) {
+    case 'running':
+      return 'Stop'
+    case 'stopped':
+    case 'not-installed':
+      return 'Start'
+    case 'starting':
+      return 'Starting…'
+    case 'stopping':
+      return 'Stopping…'
+    case 'restarting':
+      return 'Restarting…'
+    case 'installing':
+      return 'Installing…'
+    case 'updating':
+      return 'Updating…'
+    case 'removing':
+      return 'Removing…'
+    default:
+      return '—'
+  }
+}
+
+function primaryButtonClass(appId: string): string {
+  const vs = store.getAppVisualState(appId)
+  if (vs === 'running') {
+    return 'glass-button hover:text-white text-white/90 disabled:opacity-60'
+  }
+  if (vs === 'stopped' || vs === 'not-installed') {
+    return 'bg-green-600 hover:bg-green-500 disabled:bg-green-800'
+  }
+  // Transitional: muted appearance
+  return 'bg-yellow-700/40 text-yellow-200 disabled:opacity-80'
+}
+
 const backendPort = 5678
 
 function getLaunchUrl(app: BundledApp): string {
@@ -352,9 +390,23 @@ function launchApp(app: BundledApp) {
   appLauncherStore.open({ url, title: app.name })
 }
 
+async function handlePrimary(app: BundledApp) {
+  const vs = store.getAppVisualState(app.id)
+  if (vs === 'running') {
+    return handleStopApp(app.id)
+  }
+  if (vs === 'stopped' || vs === 'not-installed') {
+    return handleStartApp(app)
+  }
+  // Transitional — button should be disabled; ignore.
+}
+
 async function handleStartApp(app: BundledApp) {
   try {
-    await store.startBundledApp(app)
+    // Route through container-start (async) rather than the legacy synchronous
+    // bundled-app-start RPC so Stop/Start exercise the spawn_transitional path
+    // and the UI sees Starting → Running transitions.
+    await store.startContainer(app.id)
   } catch (e) {
     if (import.meta.env.DEV) console.error('Failed to start app:', e)
   }
@@ -362,12 +414,20 @@ async function handleStartApp(app: BundledApp) {
 
 async function handleStopApp(appId: string) {
   try {
-    await store.stopBundledApp(appId)
+    await store.stopContainer(appId)
   } catch (e) {
     if (import.meta.env.DEV) console.error('Failed to stop app:', e)
   }
 }
 
+async function handleRestartApp(appId: string) {
+  try {
+    await store.restartContainer(appId)
+  } catch (e) {
+    if (import.meta.env.DEV) console.error('Failed to restart app:', e)
+  }
+}
+
 async function handleStartContainer(name: string) {
   try {
     const appId = name.replace('archipelago-', '').replace('-dev', '')