ci: add PR previews, update guidelines, fix router basename

.github/workflows/deploy.yml

@@ -1,25 +1,24 @@
-# Workflow for deploying static content to GitHub Pages
+# Workflow for deploying static content to GitHub Pages via gh-pages branch.
+# Preserves any PR preview directories that already exist on gh-pages.
 name: Deploy static content to Pages
 
 on:
   push:
     branches: ['main']
+    paths:
+      - 'frontend/**'
   workflow_dispatch:
 
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  # Required by peaceiris/actions-gh-pages to push built site to the gh-pages branch
+  contents: write
 
 concurrency:
-  group: 'pages'
-  cancel-in-progress: true
+  group: 'gh-pages-deploy'
+  cancel-in-progress: false
 
 jobs:
   deploy:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
       # Checkout repo
@@ -41,27 +40,46 @@ jobs:
             npm install
           fi
         working-directory: ./frontend
+
       # Build project
       - name: Build
         run: npm run build
         working-directory: ./frontend
-        env: 
+        env:
           VITE_WALLETCONNECT_PROJECT_ID: ${{ secrets.VITE_WALLETCONNECT_PROJECT_ID }}
           VITE_CONTRACT_ADDRESS_11155111: ${{ secrets.VITE_CONTRACT_ADDRESS_11155111 }}
           VITE_CONTRACT_ADDRESS_61: ${{ secrets.VITE_CONTRACT_ADDRESS_61 }}
           VITE_CONTRACT_ADDRESS_137: ${{ secrets.VITE_CONTRACT_ADDRESS_137 }}
 
-      # Setup Pages
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
+      # Restore PR preview directories from gh-pages branch (if present)
+      # so that a production redeploy does not wipe them out.
+      - name: Restore PR preview directories from gh-pages
+        run: |
+          git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1 || {
+            echo "gh-pages branch does not exist yet — skipping restore."
+            exit 0
+          }
 
-      # Upload artifact
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: ./frontend/dist
+          git fetch origin gh-pages --depth=1
 
-      # Deploy to GitHub Pages
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+          # Copy the pr-preview tree into the freshly built dist so the
+          # subsequent deploy action includes it in the push.
+          git checkout origin/gh-pages -- pr-preview/ 2>/dev/null && {
+            cp -r pr-preview ./frontend/dist/pr-preview
+            rm -rf pr-preview
+          } || {
+            echo "No pr-preview directory on gh-pages yet — skipping restore."
+          }
+
+      # Add .nojekyll to prevent Jekyll processing
+      - name: Add .nojekyll
+        run: touch ./frontend/dist/.nojekyll
+
+      # Deploy to gh-pages branch
+      - name: Deploy to gh-pages branch
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./frontend/dist
+          cname: chainvoice.stability.nexus
+          commit_message: "deploy: production site from ${{ github.sha }}"

.github/workflows/pr-build.yml

@@ -0,0 +1,66 @@
+# Workflow 1 of 2 for PR previews (fork-safe).
+# This is a lightweight trigger — it only uploads metadata.
+# The actual build and deploy is handled by pr-deploy.yml via workflow_run,
+# which runs in the base repository context with secrets and write permissions.
+#
+# WHY TWO WORKFLOWS?
+# 1. Single workflow with `pull_request` + `contents: write` fails with 403
+#    on org repos where GITHUB_TOKEN defaults to read-only.
+# 2. Fork PRs never get secrets on `pull_request` trigger (GitHub blocks this).
+#    By building in pr-deploy.yml (workflow_run context), we get secrets so
+#    features like wallet connection work in PR previews.
+# 3. Fork code never gets write access — pr-deploy.yml always runs from main.
+
+name: "PR Preview: Build"
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    paths:
+      - 'frontend/**'
+
+# Read-only permissions — this workflow only uploads metadata.
+permissions:
+  contents: read
+
+jobs:
+  # ─── Signal a deploy when PR is opened or updated ───────────────────────
+  signal-deploy:
+    if: github.event.action != 'closed'
+    runs-on: ubuntu-latest
+    concurrency:
+      group: pr-preview-build-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    steps:
+      - name: Save deploy metadata
+        run: |
+          mkdir -p ./pr-metadata
+          echo "${{ github.event.pull_request.number }}" > ./pr-metadata/pr_number
+          echo "${{ github.event.pull_request.head.sha }}" > ./pr-metadata/sha
+          echo "deploy" > ./pr-metadata/action
+
+      - name: Upload PR metadata
+        uses: actions/upload-artifact@v4
+        with:
+          name: pr-metadata-${{ github.event.pull_request.number }}
+          path: ./pr-metadata
+          retention-days: 1
+
+  # ─── Signal cleanup when PR is closed (merged or abandoned) ─────────────
+  signal-cleanup:
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Save cleanup metadata
+        run: |
+          mkdir -p ./pr-metadata
+          echo "${{ github.event.pull_request.number }}" > ./pr-metadata/pr_number
+          echo "${{ github.event.pull_request.head.sha }}" > ./pr-metadata/sha
+          echo "cleanup" > ./pr-metadata/action
+
+      - name: Upload PR metadata
+        uses: actions/upload-artifact@v4
+        with:
+          name: pr-metadata-${{ github.event.pull_request.number }}
+          path: ./pr-metadata
+          retention-days: 1