Swap visual tests with hash comparison

.github/workflows/build-ultraplot.yml

@@ -71,29 +71,56 @@ jobs:
           cache-environment: true
           cache-downloads: false
 
+      # Cache Baseline Figures (Restore step)
+      - name: Cache Baseline Figures
+        id: cache-baseline
+        uses: actions/cache@v4
+        with:
+          path: ./baseline # The directory to cache
+          # Key is based on OS, Python/Matplotlib versions, and the base commit SHA
+          key: ${{ runner.os }}-baseline-${{ inputs.python-version }}-${{ inputs.matplotlib-version }}-${{ github.event.pull_request.base.sha }}
+          restore-keys: |
+            ${{ runner.os }}-baseline-${{ inputs.python-version }}-${{ inputs.matplotlib-version }}-
+
+      # Conditional Baseline Generation (Only runs on cache miss)
       - name: Generate baseline from main
+        # Skip this step if the cache was found (cache-hit is true)
+        if: steps.cache-baseline.outputs.cache-hit != 'true'
         run: |
           mkdir -p baseline
+          # Checkout the base branch (e.g., 'main') to generate the official baseline
           git fetch origin ${{ github.event.pull_request.base.sha }}
           git checkout ${{ github.event.pull_request.base.sha }}
+
+          # Install the Ultraplot version from the base branch's code
+          pip install --no-build-isolation --no-deps .
+
+          # Generate the baseline images and hash library
           python -c "import ultraplot as plt; plt.config.Configurator()._save_yaml('ultraplot.yml')"
           pytest -W ignore \
             --mpl-generate-path=./baseline/ \
+            --mpl-generate-hash-library=./baseline/baseline_hashes.json\
             --mpl-default-style="./ultraplot.yml"\
             ultraplot/tests
-          git checkout ${{ github.sha }}  # Return to PR branch
 
+          # Return to the PR branch for the rest of the job
+          git checkout ${{ github.sha }}
+
+      # Image Comparison (Uses cached or newly generated baseline)
       - name: Image Comparison Ultraplot
         run: |
+          # Re-install the Ultraplot version from the current PR branch
+          pip install --no-build-isolation --no-deps .
+
           mkdir -p results
           python -c "import ultraplot as plt; plt.config.Configurator()._save_yaml('ultraplot.yml')"
           pytest -W ignore \
-              --mpl \
-              --mpl-baseline-path=./baseline/ \
-              --mpl-results-path=./results/ \
-              --mpl-generate-summary=html \
-              --mpl-default-style="./ultraplot.yml" \
-              ultraplot/tests
+            --mpl \
+            --mpl-hash-library=./baseline/baseline_hashes.json\
+            --mpl-results-path=./results/ \
+            --mpl-generate-summary=html \
+            --mpl-default-style="./ultraplot.yml" \
+            ultraplot/tests
 
       # Return the html output of the comparison even if failed
       - name: Upload comparison failures