feat(web): show AMR cloud card as a skeleton while detection is in flight (#4112)

The onboarding "choose a runtime" step hides the Open Design AMR cloud
card until AMR's probe settles. Because AMR availability is gated behind a
live `vela model list` network call (with retries), the card was simply
absent for the several seconds detection takes on a real network, then
popped in with no loading affordance — users saw only the Local CLI / BYOK
alternatives and assumed AMR was unavailable.

Render the AMR cloud card in a skeleton state while availability is still
undecided (the cold-start detection stream is in flight, or the one-shot
re-probe has not returned). The skeleton mirrors the real card's footprint
exactly (same featured/amr grid, 246px min-height) so resolving causes no
layout jump. The AMR brand (icon + name) is known up-front and rendered
solid; only the probe-dependent parts — version meta, benefit list, and
model picker — shimmer, using the repo's existing skeleton sweep. Honors
prefers-reduced-motion.

`agentsLoading` is threaded App -> EntryView -> EntryShell -> OnboardingView
to drive the detecting window; once detection settles the card is either the
real AMR card or omitted, exactly as before.

Author: lefarcen

apps/web/src/App.tsx

@@ -2075,6 +2075,7 @@ function AppInner() {
         promptTemplates={promptTemplates}
         defaultDesignSystemId={config.designSystemId}
         agents={agents}
+        agentsLoading={agentsLoading}
         config={config}
         providerModelsCache={providerModelsCache}
         onProviderModelsCacheChange={setProviderModelsCache}

apps/web/src/components/EntryShell.tsx

@@ -296,6 +296,11 @@ interface Props {
   providerModelsCache?: ProviderModelsCache;
   onProviderModelsCacheChange?: Dispatch<SetStateAction<ProviderModelsCache>>;
   agents: AgentInfo[];
+  // True while the cold-start agent detection stream is still in flight
+  // (`fetchAgentsStream` has not reached its terminal `done`). Onboarding
+  // uses this to show the AMR cloud card in a detecting/skeleton state
+  // instead of hiding it during the seconds AMR's probe takes to settle.
+  agentsLoading?: boolean;
   daemonLive: boolean;
   onModeChange: (mode: ExecMode) => void;
   onAgentChange: (id: string) => void;
@@ -415,6 +420,7 @@ export function EntryShell({
   providerModelsCache: sharedProviderModelsCache,
   onProviderModelsCacheChange,
   agents,
+  agentsLoading = false,
   daemonLive,
   onModeChange,
   onAgentChange,
@@ -662,6 +668,7 @@ export function EntryShell({
           <OnboardingView
             config={config}
             agents={agents}
+            agentsLoading={agentsLoading}
             providerModelsCache={activeProviderModelsCache}
             onProviderModelsCacheChange={activeSetProviderModelsCache}
             daemonLive={daemonLive}
@@ -903,6 +910,7 @@ function OnboardingView({
   providerModelsCache: sharedProviderModelsCache,
   onProviderModelsCacheChange,
   agents,
+  agentsLoading = false,
   daemonLive,
   onModeChange,
   onAgentChange,
@@ -917,6 +925,7 @@ function OnboardingView({
   providerModelsCache?: ProviderModelsCache;
   onProviderModelsCacheChange?: Dispatch<SetStateAction<ProviderModelsCache>>;
   agents: AgentInfo[];
+  agentsLoading?: boolean;
   daemonLive: boolean;
   onModeChange: (mode: ExecMode) => void;
   onAgentChange: (id: string) => void;
@@ -937,6 +946,11 @@ function OnboardingView({
   const [apiKeyVisible, setApiKeyVisible] = useState(false);
   const [cliScanStatus, setCliScanStatus] = useState<'idle' | 'scanning' | 'done'>('idle');
   const [amrStatus, setAmrStatus] = useState<VelaLoginStatus | null>(null);
+  // True while the one-shot AMR re-probe (fired when the cold-start stream
+  // settled without surfacing AMR) is in flight. Combined with
+  // `agentsLoading`, this is the full window during which AMR availability
+  // is still undecided — and the AMR cloud card renders its skeleton.
+  const [amrRefreshPending, setAmrRefreshPending] = useState(false);
   const [amrLoginPending, setAmrLoginPending] = useState(false);
   const [amrLoginCancelPending, setAmrLoginCancelPending] = useState(false);
   const [newsletterSubmitting, setNewsletterSubmitting] = useState(false);
@@ -1030,7 +1044,13 @@ function OnboardingView({
     (agent) => agent.available && agent.id !== 'amr' && visibleAgentIds.includes(agent.id),
   );
   const amrAgent = agents.find((agent) => agent.id === 'amr' && agent.available) ?? null;
-  const showAmrCloudOption = amrAgent !== null || agents.length === 0;
+  // AMR availability is still undecided while the cold-start stream runs or
+  // the one-shot re-probe is in flight. During that window we show the AMR
+  // cloud card in a skeleton state rather than hiding it (the gap users hit
+  // today: card absent for several seconds, then it pops in). Once detection
+  // settles, the card is either real (amrAgent) or omitted.
+  const amrDetecting = !amrAgent && (agentsLoading || amrRefreshPending);
+  const showAmrCloudOption = amrAgent !== null;
   const amrSignedIn = amrStatus?.loggedIn === true;
   const amrSelectedAndSignedOut = runtime === 'amr' && !amrSignedIn;
   const amrAgentChoice = config.agentModels?.amr ?? {};
@@ -1070,10 +1090,16 @@ function OnboardingView({
   }, [amrAgent, onAgentChange, onModeChange, runtime]);
 
   useEffect(() => {
-    if (amrAgent || amrAgentRefreshAttemptedRef.current) return;
+    // The cold-start stream finished without AMR. Re-probe once before we
+    // conclude AMR is unavailable, and keep the card in its skeleton state
+    // for the duration so it doesn't flash out-and-back-in.
+    if (amrAgent || amrAgentRefreshAttemptedRef.current || agentsLoading) return;
     amrAgentRefreshAttemptedRef.current = true;
-    void Promise.resolve(onRefreshAgents()).catch(() => undefined);
-  }, [amrAgent, onRefreshAgents]);
+    setAmrRefreshPending(true);
+    void Promise.resolve(onRefreshAgents())
+      .catch(() => undefined)
+      .finally(() => setAmrRefreshPending(false));
+  }, [amrAgent, agentsLoading, onRefreshAgents]);
 
   useEffect(() => {
     if (!amrAgent) return;
@@ -1836,6 +1862,8 @@ function OnboardingView({
                       }}
                     />
                   </div>
+                ) : amrDetecting ? (
+                  <OnboardingAmrCloudSkeleton />
                 ) : null}
                 <div className="onboarding-view__alternatives">
                   {runtimeItems.map((item) => (
@@ -2777,6 +2805,53 @@ export function OnboardingDropdown(props: OnboardingDropdownProps) {
   );
 }
 
+// Placeholder for the AMR cloud card shown while AMR availability is still
+// being probed (the cold-start detection stream / one-shot re-probe). It
+// mirrors the real card's footprint exactly — same featured/amr grid, same
+// 246px min-height — so resolving to the real card causes no layout jump.
+// The AMR brand (icon + name) is known up-front and rendered solid; only the
+// version meta, benefit list, and model picker — the parts that depend on the
+// probe result — shimmer. Non-interactive and announced via role="status".
+function OnboardingAmrCloudSkeleton() {
+  const t = useT();
+  return (
+    <div className="onboarding-view__amr-cloud-card">
+      <div
+        className="onboarding-view__card onboarding-view__card--featured onboarding-view__card--amr onboarding-view__card--benefit-aside onboarding-view__card--skeleton"
+        role="status"
+        aria-busy="true"
+        aria-label={t('common.loading')}
+      >
+        <span className="onboarding-view__identity">
+          <span className="onboarding-view__icon onboarding-view__icon--asset">
+            <AgentIcon id="amr" size={52} className="onboarding-view__agent-logo" />
+          </span>
+          <span className="onboarding-view__card-copy">
+            <span className="onboarding-view__card-top">
+              <strong>{t('settings.amrCloud')}</strong>
+            </span>
+            <span className="onboarding-view__skeleton-line onboarding-view__skeleton-line--meta" />
+          </span>
+        </span>
+        <span className="onboarding-view__benefit-aside" aria-hidden="true">
+          <span className="onboarding-view__benefit-stack onboarding-view__benefit-stack--skeleton">
+            <span className="onboarding-view__skeleton-line onboarding-view__skeleton-line--benefit" />
+            <span className="onboarding-view__skeleton-line onboarding-view__skeleton-line--benefit" />
+            <span className="onboarding-view__skeleton-line onboarding-view__skeleton-line--benefit" />
+            <span className="onboarding-view__skeleton-line onboarding-view__skeleton-line--benefit" />
+          </span>
+        </span>
+        <span className="onboarding-view__card-model" aria-hidden="true">
+          <span className="onboarding-view__skeleton-model">
+            <span className="onboarding-view__skeleton-model-label" />
+            <span className="onboarding-view__skeleton-model-bar" />
+          </span>
+        </span>
+      </div>
+    </div>
+  );
+}
+
 function OnboardingChoiceCard({
   icon,
   agentIconId,

apps/web/src/components/EntryView.tsx

@@ -54,6 +54,9 @@ interface Props {
   promptTemplates: PromptTemplateSummary[];
   defaultDesignSystemId: string | null;
   agents: AgentInfo[];
+  // Forwarded to EntryShell → OnboardingView so the AMR cloud card can show a
+  // detecting/skeleton state while the cold-start agent stream is in flight.
+  agentsLoading?: boolean;
   // Execution / model-switching context forwarded to the EntryShell so the
   // sticky top-bar can expose the active CLI/BYOK + model and persist
   // changes through the same channels as the project view.
@@ -222,6 +225,7 @@ export function EntryView({
   promptTemplates,
   defaultDesignSystemId,
   agents,
+  agentsLoading,
   config,
   providerModelsCache,
   onProviderModelsCacheChange,
@@ -343,6 +347,7 @@ export function EntryView({
       providerModelsCache={providerModelsCache}
       onProviderModelsCacheChange={onProviderModelsCacheChange}
       agents={agents}
+      {...(agentsLoading !== undefined ? { agentsLoading } : {})}
       daemonLive={daemonLive}
       onModeChange={onModeChange}
       onAgentChange={onAgentChange}

apps/web/src/styles/home/entry-layout.css

@@ -3441,3 +3441,123 @@
   }
 
 }
+
+/* ============================================================
+   AMR cloud card — detecting / skeleton state
+   Shown while AMR availability is still being probed. Reuses the
+   featured/amr card classes (so min-height: 246px and the responsive
+   grid are inherited — no layout jump when the real card resolves).
+   Only the probe-dependent parts shimmer; the brand stays solid.
+   ============================================================ */
+.onboarding-view__card--skeleton {
+  cursor: default;
+  /* Neutral, un-selected resting surface — the card is not yet actionable,
+     so it must not read as the accent-selected state. */
+  border-color: var(--border);
+  background: var(--bg-panel);
+  box-shadow: var(--shadow-xs);
+}
+
+.onboarding-view__card--skeleton:hover {
+  /* Defeat the interactive card's hover lift/tint while detecting. */
+  border-color: var(--border);
+  background: var(--bg-panel);
+  transform: none;
+}
+
+/* Shared shimmer fill — matches the house skeleton sweep
+   (recent-projects / plugins-home): a soft highlight passing over a
+   muted base. Sheen kept intentionally low-contrast for a precise,
+   non-flashy read. */
+.onboarding-view__skeleton-line,
+.onboarding-view__skeleton-model-label,
+.onboarding-view__skeleton-model-bar {
+  display: block;
+  border-radius: var(--radius-pill);
+  background:
+    linear-gradient(
+      110deg,
+      transparent 28%,
+      color-mix(in srgb, #fff 30%, transparent) 50%,
+      transparent 72%
+    ) 0 0 / 200% 100%,
+    color-mix(in srgb, var(--bg-muted) 82%, var(--bg-panel));
+  animation: onboarding-skeleton-sheen 1.55s ease-in-out infinite;
+}
+
+[data-theme="dark"] .onboarding-view__skeleton-line,
+[data-theme="dark"] .onboarding-view__skeleton-model-label,
+[data-theme="dark"] .onboarding-view__skeleton-model-bar {
+  background:
+    linear-gradient(
+      110deg,
+      transparent 28%,
+      color-mix(in srgb, #fff 12%, transparent) 50%,
+      transparent 72%
+    ) 0 0 / 200% 100%,
+    color-mix(in srgb, var(--bg-elevated) 70%, var(--bg-muted));
+}
+
+/* Version meta placeholder (sits where "AMR v0.1.0" renders). */
+.onboarding-view__skeleton-line--meta {
+  width: 116px;
+  height: 11px;
+  margin-top: 2px;
+}
+
+/* Benefit list placeholders in the aside column. Staggered widths read as
+   real copy rather than a stack of identical bars. */
+.onboarding-view__benefit-stack--skeleton {
+  gap: 11px;
+}
+
+.onboarding-view__skeleton-line--benefit {
+  height: 13px;
+  border-radius: var(--radius-sm);
+}
+.onboarding-view__benefit-stack--skeleton
+  .onboarding-view__skeleton-line--benefit:nth-child(1) { width: 90%; }
+.onboarding-view__benefit-stack--skeleton
+  .onboarding-view__skeleton-line--benefit:nth-child(2) { width: 74%; }
+.onboarding-view__benefit-stack--skeleton
+  .onboarding-view__skeleton-line--benefit:nth-child(3) { width: 83%; }
+.onboarding-view__benefit-stack--skeleton
+  .onboarding-view__skeleton-line--benefit:nth-child(4) { width: 58%; }
+
+/* Model picker placeholder (sits where the AMR model select renders). */
+.onboarding-view__skeleton-model {
+  display: grid;
+  gap: 8px;
+  width: min(260px, 100%);
+}
+.onboarding-view__card--amr .onboarding-view__skeleton-model {
+  width: 100%;
+}
+.onboarding-view__skeleton-model-label {
+  width: 96px;
+  height: 11px;
+}
+.onboarding-view__skeleton-model-bar {
+  width: 100%;
+  height: 40px;
+  border-radius: var(--radius);
+  /* Slightly stagger the sweep from the label so the two don't pulse in
+     lockstep — reads as one surface loading, not two blinking blocks. */
+  animation-delay: 160ms;
+}
+
+@keyframes onboarding-skeleton-sheen {
+  to {
+    background-position: -200% 0, 0 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .onboarding-view__skeleton-line,
+  .onboarding-view__skeleton-model-label,
+  .onboarding-view__skeleton-model-bar {
+    animation: none;
+    background:
+      color-mix(in srgb, var(--bg-muted) 82%, var(--bg-panel));
+  }
+}

apps/web/tests/components/EntryShell.onboarding.test.tsx

@@ -820,6 +820,43 @@ describe('EntryShell onboarding Open Design AMR runtime', () => {
     });
   });
 
+  it('shows the AMR cloud card as a skeleton while agent detection is still in flight', async () => {
+    // Before this fix, the AMR cloud card was simply absent for the several
+    // seconds AMR's probe takes to settle (showAmrCloudOption was false once
+    // any non-AMR agent had arrived), then popped in with no loading state.
+    globalThis.fetch = vi.fn(async () =>
+      jsonResponse({ loggedIn: false, profile: 'prod', user: null, configPath: '/x' }),
+    ) as typeof fetch;
+    renderOnboarding({
+      agents: [cliAgent()], // AMR has not surfaced from the stream yet
+      agentsLoading: true, // cold-start detection stream still running
+      onRefreshAgents: vi.fn(() => [cliAgent()]),
+    });
+
+    const skeleton = document.querySelector('.onboarding-view__card--skeleton');
+    expect(skeleton).toBeTruthy();
+    // The brand identity is known up-front and rendered solid; only the
+    // probe-dependent details shimmer.
+    expect(skeleton?.textContent).toContain('Open Design AMR');
+    expect(skeleton?.getAttribute('aria-busy')).toBe('true');
+    expect(skeleton?.querySelectorAll('.onboarding-view__skeleton-line--benefit').length).toBe(4);
+    expect(skeleton?.querySelector('.onboarding-view__skeleton-model-bar')).toBeTruthy();
+    // The real, selectable AMR card is not present while detecting.
+    expect(screen.queryByRole('button', { name: /Open Design AMR/i })).toBeNull();
+    // Alternatives remain available throughout detection.
+    expect(screen.getByRole('button', { name: /Local coding agent/i })).toBeTruthy();
+  });
+
+  it('renders the real AMR cloud card and no skeleton once AMR is available', async () => {
+    globalThis.fetch = vi.fn(async () =>
+      jsonResponse({ loggedIn: false, profile: 'prod', user: null, configPath: '/x' }),
+    ) as typeof fetch;
+    renderOnboarding({ agentsLoading: false });
+
+    expect(screen.getByRole('button', { name: /Open Design AMR/i })).toBeTruthy();
+    expect(document.querySelector('.onboarding-view__card--skeleton')).toBeNull();
+  });
+
   it('lets Skip exit onboarding without starting AMR login', async () => {
     const fetchMock = vi.fn(async (_input: RequestInfo | URL) =>
       jsonResponse({ loggedIn: false, profile: 'prod', user: null, configPath: '/x' }),