fix(app): stacker error recovery shouldn't call manualRetrieve pre-maturely (#18824)

This PR fixes the following error recovery issues:
1. We skipped a step in the `STACKER_SHUTTLE_EMPTY_SKIP` route by
routing to the wrong step in `HoldingLabware`
2. The `flexStackerLabwareRetrieveFailed` error was not caught in our
failedLabwareUtil so we've been rendering incorrect labware info for the
`STACKER_SHUTTLE_EMPTY_SKIP/RETRY` routes
3. The re-engage latch PNG was not rendered properly because we rendered
it as a video instead of an image
4. `ReleaseLabware` screen now renders a latch release animation instead
of gripper for stacker-related flows
5. We prematurely called `manualRetrieve` and changed the stacker state
before exiting the flow. When a user tries to go back to a previous
step, the rest of the flow would always end up failing. To fix this, the
`manualRetrieve` happens in the last step of the flow.
6. Updating the hopper labware info screen to reflect the correct number
after a potential manual retrieval, since now we won't get the state
change to occur until the flow is completed

Author: ahiuchingau

app/src/organisms/ErrorRecoveryFlows/hooks/useFailedLabwareUtils.ts

@@ -374,6 +374,7 @@ export function getRelevantLabwareIdFromFailedCmd(
       'flexStackerStallOrCollision',
       'flexStackerShuttleMissing',
       'flexStackerHopperLabwareFailed',
+      'flexStackerLabwareRetrieveFailed',
     ].includes(error.errorType)
   if (recentRelevantFailedLabwareCmd == null) {
     return null

app/src/organisms/ErrorRecoveryFlows/shared/HoldingLabware.tsx

@@ -90,7 +90,7 @@ export function HoldingLabware({
           case STACKER_SHUTTLE_EMPTY_SKIP.ROUTE:
             return proceedToRouteAndStep(
               STACKER_SHUTTLE_EMPTY_SKIP.ROUTE,
-              STACKER_SHUTTLE_EMPTY_SKIP.STEPS.FILL_HOPPER
+              STACKER_SHUTTLE_EMPTY_SKIP.STEPS.PLACE_LABWARE_ON_SHUTTLE
             )
           default: {
             console.error('Unexpected recovery option for gripper routing.')

app/src/organisms/ErrorRecoveryFlows/shared/LeftColumnLabwareInfo.tsx

@@ -12,6 +12,7 @@ type LeftColumnLabwareInfoProps = RecoveryContentProps & {
   layout: ComponentProps<typeof InterventionContent>['infoProps']['layout']
   /* Renders a warning InlineNotification if provided. */
   bannerText?: string | null
+  showQuantity?: boolean
 }
 // TODO(jh, 06-12-24): EXEC-500 & EXEC-501.
 // The left column component adjacent to RecoveryDeckMap/TipSelection.
@@ -22,6 +23,7 @@ export function LeftColumnLabwareInfo({
   layout,
   bannerText,
   recoveryMap,
+  showQuantity = true,
 }: LeftColumnLabwareInfoProps): JSX.Element {
   const { step, route } = recoveryMap
   const {
@@ -69,6 +71,7 @@ export function LeftColumnLabwareInfo({
       switch (step) {
         case STACKER_STALLED_RETRY.STEPS.CHECK_HOPPER:
         case STACKER_STALLED_SKIP.STEPS.CHECK_HOPPER:
+        case STACKER_SHUTTLE_EMPTY_SKIP.STEPS.FILL_HOPPER:
           return {
             labwareName: failedLabwareNames.name ?? '',
             labwareNickname: failedLabwareNames.nickName,
@@ -78,7 +81,7 @@ export function LeftColumnLabwareInfo({
           }
         case STACKER_STALLED_SKIP.STEPS.PLACE_LABWARE_ON_SHUTTLE:
         case STACKER_HOPPER_EMPTY_SKIP.STEPS.PLACE_LABWARE_ON_SHUTTLE:
-        case STACKER_SHUTTLE_EMPTY_SKIP.STEPS.FILL_HOPPER:
+        case STACKER_SHUTTLE_EMPTY_SKIP.STEPS.PLACE_LABWARE_ON_SHUTTLE:
           return {
             labwareName: failedLabwareNames.name ?? '',
             labwareNickname: failedLabwareNames.nickName,
@@ -99,16 +102,22 @@ export function LeftColumnLabwareInfo({
   }
 
   const buildQuantity = (): number | null => {
-    switch (step) {
-      case STACKER_STALLED_RETRY.STEPS.CHECK_HOPPER:
-      case STACKER_STALLED_SKIP.STEPS.CHECK_HOPPER:
-      case STACKER_HOPPER_EMPTY_SKIP.STEPS.FILL_HOPPER:
-        return labwareQuantity
-      case STACKER_STALLED_SKIP.STEPS.PLACE_LABWARE_ON_SHUTTLE:
-      case STACKER_HOPPER_EMPTY_SKIP.STEPS.PLACE_LABWARE_ON_SHUTTLE:
-        return null
-      default:
-        return labwareQuantity
+    if (!showQuantity) {
+      return null
+    }
+    if (
+      (route === RECOVERY_MAP.STACKER_HOPPER_EMPTY_SKIP.ROUTE &&
+        step === RECOVERY_MAP.STACKER_HOPPER_EMPTY_SKIP.STEPS.FILL_HOPPER) ||
+      (route === RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_SKIP.ROUTE &&
+        step === RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_SKIP.STEPS.FILL_HOPPER) ||
+      (route === RECOVERY_MAP.STACKER_STALLED_SKIP.ROUTE &&
+        step === RECOVERY_MAP.STACKER_STALLED_SKIP.STEPS.CHECK_HOPPER)
+    ) {
+      return labwareQuantity != null && labwareQuantity > 0
+        ? labwareQuantity - 1 // one has been moved manually onto the shuttle
+        : null
+    } else {
+      return labwareQuantity ?? null
     }
   }
 

app/src/organisms/ErrorRecoveryFlows/shared/ReleaseLabware.tsx

@@ -12,6 +12,7 @@ import {
   StyledText,
 } from '@opentrons/components'
 
+import stackerReleaseLatchAnimation from '/app/assets/videos/error-recovery/FlexStacker_ReleaseLatch.webm'
 import gripperReleaseAnimation from '/app/assets/videos/error-recovery/Gripper_Release.webm'
 import { TwoColumn } from '/app/molecules/InterventionModal'
 import { RECOVERY_MAP } from '/app/organisms/ErrorRecoveryFlows/constants'
@@ -72,6 +73,12 @@ export function ReleaseLabware({
         return t('take_any_necessary_precautions')
     }
   }
+  const animationSrc =
+    route === STACKER_SHUTTLE_EMPTY_RETRY.ROUTE ||
+    route === STACKER_SHUTTLE_EMPTY_SKIP.ROUTE
+      ? stackerReleaseLatchAnimation
+      : gripperReleaseAnimation
+
   return (
     <RecoverySingleColumnContentWrapper>
       <TwoColumn>
@@ -95,10 +102,7 @@ export function ReleaseLabware({
         </Flex>
         <Flex css={ANIMATION_CONTAINER_STYLE}>
           <AnimationVideo role="presentation" css={ANIMATION_STYLE}>
-            <source
-              src={gripperReleaseAnimation}
-              data-testid="gripper-animation"
-            />
+            <source src={animationSrc} data-testid="release-animation" />
           </AnimationVideo>
         </Flex>
       </TwoColumn>

app/src/organisms/ErrorRecoveryFlows/shared/SkipStepInfo.tsx

@@ -24,19 +24,28 @@ export function SkipStepInfo(props: RecoveryContentProps): JSX.Element {
   } = RECOVERY_MAP
   const { selectedRecoveryOption } = currentRecoveryOptionUtils
   const { skipFailedCommand } = recoveryCommands
-  const { moveLabwareWithoutPause } = recoveryCommands
+  const { moveLabwareWithoutPause, manualRetrieve } = recoveryCommands
   const { handleMotionRouting } = routeUpdateActions
   const { ROBOT_SKIPPING_STEP } = RECOVERY_MAP
   const { t } = useTranslation('error_recovery')
 
   const primaryBtnOnClick = (): Promise<void> => {
     return handleMotionRouting(true, ROBOT_SKIPPING_STEP.ROUTE).then(() => {
-      if (selectedRecoveryOption === MANUAL_MOVE_AND_SKIP.ROUTE) {
-        void moveLabwareWithoutPause().then(() => {
+      switch (selectedRecoveryOption) {
+        case MANUAL_MOVE_AND_SKIP.ROUTE:
+          void moveLabwareWithoutPause().then(() => {
+            skipFailedCommand()
+          })
+          break
+        case STACKER_HOPPER_EMPTY_SKIP.ROUTE:
+        case STACKER_SHUTTLE_EMPTY_SKIP.ROUTE:
+        case STACKER_STALLED_SKIP.ROUTE:
+          void manualRetrieve().then(() => {
+            skipFailedCommand()
+          })
+          break
+        default:
           skipFailedCommand()
-        })
-      } else {
-        skipFailedCommand()
       }
     })
   }

app/src/organisms/ErrorRecoveryFlows/shared/StackerReengageLatch.tsx

@@ -1,11 +1,13 @@
 import { useTranslation } from 'react-i18next'
+import { css } from 'styled-components'
+
+import { JUSTIFY_CENTER, RESPONSIVENESS } from '@opentrons/components'
 
 import ReengageLatch from '/app/assets/images/flex_stacker_reengage_latch.png'
 import { DescriptionContent, TwoColumn } from '/app/molecules/InterventionModal'
 
 import { RecoverySingleColumnContentWrapper } from './RecoveryContentWrapper'
 import { RecoveryFooterButtons } from './RecoveryFooterButtons'
-import { RightColumnAnimation } from './RightColumnAnimation'
 
 import type { RecoveryContentProps } from '../types'
 
@@ -22,7 +24,7 @@ export function StackerReengageLatch(props: RecoveryContentProps): JSX.Element {
           headline={t('prepare_for_stacker_latch_reengage')}
           message={t('stacker_latch_will_reengage')}
         />
-        <RightColumnAnimation animationSrc={ReengageLatch} />
+        <img src={ReengageLatch} css={IMAGE_STYLE} />
       </TwoColumn>
       <RecoveryFooterButtons
         primaryBtnOnClick={proceedNextStep}
@@ -31,3 +33,14 @@ export function StackerReengageLatch(props: RecoveryContentProps): JSX.Element {
     </RecoverySingleColumnContentWrapper>
   )
 }
+
+const IMAGE_STYLE = css`
+  justify-content: ${JUSTIFY_CENTER};
+  overflow: hidden;
+  max-height: 13.25rem;
+
+  @media ${RESPONSIVENESS.touchscreenMediaQuerySpecs} {
+    width: 27rem;
+    height: 20.25rem;
+  }
+`

app/src/organisms/ErrorRecoveryFlows/shared/StackerShuttleLwInfo.tsx

@@ -11,16 +11,8 @@ import { RightColumnAnimation } from './RightColumnAnimation'
 import type { RecoveryContentProps } from '../types'
 
 export function StackerShuttleLwInfo(props: RecoveryContentProps): JSX.Element {
-  const { recoveryCommands, routeUpdateActions } = props
-  const { manualRetrieve } = recoveryCommands
-  const { proceedNextStep } = routeUpdateActions
-
   const { t } = useTranslation('error_recovery')
 
-  const primaryOnClick = (): void => {
-    void manualRetrieve().then(() => proceedNextStep())
-  }
-
   return (
     <RecoverySingleColumnContentWrapper>
       <TwoColumn>
@@ -29,11 +21,12 @@ export function StackerShuttleLwInfo(props: RecoveryContentProps): JSX.Element {
           title={t('load_labware_into_labware_shuttle')}
           type={'location'}
           layout={'stacked'}
+          showQuantity={false}
         />
         <RightColumnAnimation animationSrc={ShuttleLabware} />
       </TwoColumn>
       <RecoveryFooterButtons
-        primaryBtnOnClick={primaryOnClick}
+        primaryBtnOnClick={props.routeUpdateActions.proceedNextStep}
         secondaryBtnOnClick={props.routeUpdateActions.goBackPrevStep}
       />
     </RecoverySingleColumnContentWrapper>

app/src/organisms/ErrorRecoveryFlows/shared/__tests__/HoldingLabware.test.tsx

@@ -193,7 +193,7 @@ describe('HoldingLabware', () => {
     await waitFor(() => {
       expect(mockProceedToRouteAndStep).toHaveBeenCalledWith(
         RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_SKIP.ROUTE,
-        RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_SKIP.STEPS.FILL_HOPPER
+        RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_SKIP.STEPS.PLACE_LABWARE_ON_SHUTTLE
       )
     })
   })

app/src/organisms/ErrorRecoveryFlows/shared/__tests__/ReleaseLabware.test.tsx

@@ -16,6 +16,13 @@ vi.mock('/app/assets/videos/error-recovery/Gripper_Release.webm', () => ({
   default: 'mocked-animation-path.webm',
 }))
 
+vi.mock(
+  '/app/assets/videos/error-recovery/FlexStacker_ReleaseLatch.webm',
+  () => ({
+    default: 'mocked-stacker-latch-path.webm',
+  })
+)
+
 const render = (props: ComponentProps<typeof ReleaseLabware>) => {
   return renderWithProviders(<ReleaseLabware {...props} />, {
     i18nInstance: i18n,
@@ -26,58 +33,99 @@ describe('ReleaseLabware', () => {
   let props: ComponentProps<typeof ReleaseLabware>
   let mockHandleMotionRouting: Mock
 
-  beforeEach(() => {
-    mockHandleMotionRouting = vi.fn(() => Promise.resolve())
-
-    props = {
-      ...mockRecoveryContentProps,
-      routeUpdateActions: {
-        handleMotionRouting: mockHandleMotionRouting,
-        goBackPrevStep: vi.fn(),
-      } as any,
-    }
+  describe('For gripper flows', () => {
+    beforeEach(() => {
+      mockHandleMotionRouting = vi.fn(() => Promise.resolve())
+
+      props = {
+        ...mockRecoveryContentProps,
+        routeUpdateActions: {
+          handleMotionRouting: mockHandleMotionRouting,
+          goBackPrevStep: vi.fn(),
+        } as any,
+      }
+    })
+
+    it('renders gripper copy', () => {
+      render(props)
+
+      screen.getByText('Release labware from gripper')
+      screen.getByText(
+        'Take any necessary precautions before positioning yourself to stabilize or catch the labware. Once confirmed, a countdown will begin before the gripper releases.'
+      )
+      screen.getByText('The labware will be released from its current height.')
+    })
+
+    it(`clicking the primary button routes to ${RECOVERY_MAP.ROBOT_RELEASING_LABWARE.ROUTE}`, () => {
+      render(props)
+
+      clickButtonLabeled('Release')
+
+      expect(mockHandleMotionRouting).toHaveBeenCalledWith(
+        true,
+        RECOVERY_MAP.ROBOT_RELEASING_LABWARE.ROUTE
+      )
+    })
+
+    it('renders gripper animation', () => {
+      render(props)
+
+      screen.getByRole('presentation', { hidden: true })
+      expect(screen.getByTestId('release-animation')).toHaveAttribute(
+        'src',
+        'mocked-animation-path.webm'
+      )
+    })
   })
 
-  it('renders gripper copy', () => {
-    render(props)
-
-    screen.getByText('Release labware from gripper')
-    screen.getByText(
-      'Take any necessary precautions before positioning yourself to stabilize or catch the labware. Once confirmed, a countdown will begin before the gripper releases.'
-    )
-    screen.getByText('The labware will be released from its current height.')
-  })
-
-  it('renders latch copy', () => {
-    props.recoveryMap = {
-      route: RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_RETRY.ROUTE,
-      step:
-        RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_RETRY.STEPS.CONFIRM_LABWARE_IN_LATCH,
-    }
-    render(props)
-
-    screen.getByText('Release labware from latch')
-    screen.getByText(
-      'Take any necessary precautions before positioning yourself to stabilize or catch the labware if needed. Once confirmed, a countdown will begin before the latch releases.'
-    )
-    screen.getByText('The labware will be released from its current height.')
-  })
-
-  it('clicking the primary button has correct behavior', () => {
-    render(props)
-
-    clickButtonLabeled('Release')
-
-    expect(mockHandleMotionRouting).toHaveBeenCalled()
-  })
-
-  it('renders gripper animation', () => {
-    render(props)
-
-    screen.getByRole('presentation', { hidden: true })
-    expect(screen.getByTestId('gripper-animation')).toHaveAttribute(
-      'src',
-      'mocked-animation-path.webm'
-    )
+  describe('For stacker flows', () => {
+    beforeEach(() => {
+      mockHandleMotionRouting = vi.fn(() => Promise.resolve())
+
+      props = {
+        ...mockRecoveryContentProps,
+        recoveryMap: {
+          route: RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_RETRY.ROUTE,
+          step:
+            RECOVERY_MAP.STACKER_SHUTTLE_EMPTY_RETRY.STEPS
+              .CONFIRM_LABWARE_IN_LATCH,
+        },
+        routeUpdateActions: {
+          handleMotionRouting: mockHandleMotionRouting,
+          goBackPrevStep: vi.fn(),
+        } as any,
+      }
+    })
+
+    it('renders latch copy', () => {
+      render(props)
+
+      screen.getByText('Release labware from latch')
+      screen.getByText(
+        'Take any necessary precautions before positioning yourself to stabilize or catch the labware if needed. Once confirmed, a countdown will begin before the latch releases.'
+      )
+      screen.getByText('The labware will be released from its current height.')
+    })
+
+    it(`clicking the primary button routes to ${RECOVERY_MAP.ROBOT_RELEASING_LABWARE_LATCH.ROUTE}`, () => {
+      render(props)
+
+      clickButtonLabeled('Release')
+
+      expect(mockHandleMotionRouting).toHaveBeenCalledWith(
+        true,
+        RECOVERY_MAP.ROBOT_RELEASING_LABWARE_LATCH.ROUTE
+      )
+    })
+
+    it('renders latch animation', () => {
+      render(props)
+
+      screen.getByRole('presentation', { hidden: true })
+      expect(screen.getByTestId('release-animation')).toHaveAttribute(
+        'src',
+        'mocked-stacker-latch-path.webm'
+      )
+    })
   })
 })