feat: add branch-specific PR preview environments

.github/workflows/build-preview.yml

@@ -0,0 +1,129 @@
+name: Build Preview
+
+on:
+  pull_request:
+    branches:
+      - main
+      - develop
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+permissions:
+  contents: read
+
+concurrency:
+  group: build-preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  build-preview:
+    name: Build Web Preview
+    runs-on: ubuntu-latest
+    env:
+      EMSDK_VERSION: 3.1.51
+    steps:
+      - name: Checkout PR commit
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Cache Emscripten SDK & ports
+        uses: actions/cache@v5
+        id: emsdk-cache
+        with:
+          path: |
+            emsdk
+            ~/.emscripten_cache
+          key: emsdk-${{ env.EMSDK_VERSION }}-${{ runner.os }}-${{ hashFiles('CMakeLists.txt') }}
+          restore-keys: |
+            emsdk-${{ env.EMSDK_VERSION }}-${{ runner.os }}-
+
+      - name: Setup Emscripten
+        if: steps.emsdk-cache.outputs.cache-hit != 'true'
+        run: |
+          if [ -d emsdk ]; then
+            cd emsdk && git pull
+          else
+            git clone https://github.com/emscripten-core/emsdk.git
+            cd emsdk
+          fi
+          ./emsdk install $EMSDK_VERSION
+          ./emsdk activate $EMSDK_VERSION
+
+      - name: Activate Emscripten
+        run: |
+          cd emsdk
+          ./emsdk activate $EMSDK_VERSION
+          echo "${{ github.workspace }}/emsdk" >> "$GITHUB_PATH"
+          echo "${{ github.workspace }}/emsdk/upstream/emscripten" >> "$GITHUB_PATH"
+
+      - name: Setup External Dependencies
+        run: |
+          git clone --depth 1 --branch v1.90.1 https://github.com/ocornut/imgui.git external/imgui &
+          curl -sL -o external/nanosvg.h https://raw.githubusercontent.com/memononen/nanosvg/master/src/nanosvg.h &
+          curl -sL -o external/nanosvgrast.h https://raw.githubusercontent.com/memononen/nanosvg/master/src/nanosvgrast.h &
+          curl -sL -o external/dr_wav.h https://raw.githubusercontent.com/mackron/dr_libs/master/dr_wav.h &
+          mkdir -p external/kiss_fft
+          curl -sL -o external/kiss_fft/kiss_fft.h https://raw.githubusercontent.com/mborgerding/kissfft/master/kiss_fft.h &
+          curl -sL -o external/kiss_fft/kiss_fft.c https://raw.githubusercontent.com/mborgerding/kissfft/master/kiss_fft.c &
+          curl -sL -o external/kiss_fft/_kiss_fft_guts.h https://raw.githubusercontent.com/mborgerding/kissfft/master/_kiss_fft_guts.h &
+          curl -sL -o external/kiss_fft/kiss_fft_log.h https://raw.githubusercontent.com/mborgerding/kissfft/master/kiss_fft_log.h &
+          wait
+
+      - name: Generate Preview Version
+        id: version
+        run: |
+          COUNT=$(git rev-list --count HEAD)
+          echo "version=0.1.${COUNT}-pr.${{ github.event.pull_request.number }}.${{ github.run_number }}" >> "$GITHUB_OUTPUT"
+
+      - name: Build WASM
+        run: |
+          source emsdk/emsdk_env.sh
+          mkdir -p build-web && cd build-web
+          emcmake cmake -DCMAKE_BUILD_TYPE=Release -DAMPLITRON_VERSION="${{ steps.version.outputs.version }}" ..
+          emmake make -j"$(nproc)"
+
+      - name: Stage preview artifact
+        run: |
+          mkdir -p preview .preview-meta
+
+          for file in \
+            build-web/index.html \
+            build-web/index.js \
+            build-web/index.wasm \
+            build-web/index.data \
+            build-web/*.worker.js \
+            build-web/coi-serviceworker.js
+          do
+            [ -e "$file" ] && cp "$file" preview/
+          done
+
+          test -f preview/index.html
+          test -f preview/index.js
+          test -f preview/index.wasm
+          touch preview/.nojekyll
+
+          cat > .preview-meta/preview.env <<EOF
+          PR_NUMBER=${{ github.event.pull_request.number }}
+          HEAD_SHA=${{ github.event.pull_request.head.sha }}
+          PREVIEW_PATH=pr-previews/pr-${{ github.event.pull_request.number }}
+          PREVIEW_URL=https://amplitron.sudipmondal.co.in/pr-previews/pr-${{ github.event.pull_request.number }}/
+          EOF
+
+      - name: Upload preview artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: pr-preview
+          path: preview/
+          retention-days: 3
+
+      - name: Upload preview metadata
+        uses: actions/upload-artifact@v7
+        with:
+          name: pr-preview-metadata
+          path: .preview-meta/
+          retention-days: 3

.github/workflows/deploy-preview.yml

@@ -0,0 +1,199 @@
+name: Deploy Preview
+
+on:
+  workflow_run:
+    workflows:
+      - Build Preview
+    types:
+      - completed
+  pull_request_target:
+    types:
+      - closed
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: deploy-preview-${{ github.event.workflow_run.id || github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  deploy-preview:
+    name: Deploy PR Preview
+    if: >
+      github.event_name == 'workflow_run' &&
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download preview artifact
+        uses: actions/download-artifact@v8
+        with:
+          name: pr-preview
+          path: preview
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Download preview metadata
+        uses: actions/download-artifact@v8
+        with:
+          name: pr-preview-metadata
+          path: .preview-meta
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Load preview metadata
+        id: preview-meta
+        run: |
+          set -a
+          . .preview-meta/preview.env
+          set +a
+
+          echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+          echo "head_sha=$HEAD_SHA" >> "$GITHUB_OUTPUT"
+          echo "preview_path=$PREVIEW_PATH" >> "$GITHUB_OUTPUT"
+          echo "preview_url=$PREVIEW_URL" >> "$GITHUB_OUTPUT"
+          echo "short_sha=${HEAD_SHA:0:7}" >> "$GITHUB_OUTPUT"
+
+      - name: Check pull request state
+        id: pr-state
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pull_number = Number('${{ steps.preview-meta.outputs.pr_number }}');
+            const { data: pull } = await github.rest.pulls.get({
+              owner,
+              repo,
+              pull_number,
+            });
+            core.setOutput('state', pull.state);
+
+      - name: Publish preview to GitHub Pages
+        if: steps.pr-state.outputs.state == 'open'
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./preview
+          publish_branch: gh-pages
+          destination_dir: ${{ steps.preview-meta.outputs.preview_path }}
+          keep_files: true
+          enable_jekyll: false
+
+      - name: Comment preview URL on PR
+        if: steps.pr-state.outputs.state == 'open'
+        uses: actions/github-script@v8
+        env:
+          PR_NUMBER: ${{ steps.preview-meta.outputs.pr_number }}
+          PREVIEW_URL: ${{ steps.preview-meta.outputs.preview_url }}
+          PREVIEW_PATH: ${{ steps.preview-meta.outputs.preview_path }}
+          SHORT_SHA: ${{ steps.preview-meta.outputs.short_sha }}
+        with:
+          script: |
+            const marker = '<!-- amplitron-pr-preview -->';
+            const { owner, repo } = context.repo;
+            const issue_number = Number(process.env.PR_NUMBER);
+            const body = [
+              marker,
+              '### PR Preview Ready',
+              '',
+              `Preview URL: ${process.env.PREVIEW_URL}`,
+              '',
+              `Built from commit \`${process.env.SHORT_SHA}\` and deployed to \`${process.env.PREVIEW_PATH}\`.`,
+              'This preview updates automatically when the PR branch changes and is removed when the PR closes.',
+            ].join('\n');
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner,
+              repo,
+              issue_number,
+              per_page: 100,
+            });
+            const previous = comments.find((comment) =>
+              comment.user?.type === 'Bot' && comment.body?.includes(marker)
+            );
+
+            if (previous) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: previous.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body,
+              });
+            }
+
+  cleanup-preview:
+    name: Remove Closed PR Preview
+    if: github.event_name == 'pull_request_target'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout GitHub Pages branch
+        id: pages-checkout
+        uses: actions/checkout@v6
+        continue-on-error: true
+        with:
+          ref: gh-pages
+          path: pages
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Remove preview directory
+        if: steps.pages-checkout.outcome == 'success'
+        working-directory: pages
+        env:
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          target="pr-previews/pr-${PR_NUMBER}"
+
+          if [ ! -d "$target" ]; then
+            echo "No preview directory found at $target"
+            exit 0
+          fi
+
+          rm -rf "$target"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add -A "$target"
+          git commit -m "Remove preview for PR #${PR_NUMBER}"
+          git push
+
+      - name: Comment cleanup on PR
+        if: steps.pages-checkout.outcome == 'success'
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const marker = '<!-- amplitron-pr-preview -->';
+            const { owner, repo } = context.repo;
+            const issue_number = context.payload.pull_request.number;
+            const body = [
+              marker,
+              '### PR Preview Removed',
+              '',
+              'The GitHub Pages preview for this PR has been removed because the PR was closed.',
+            ].join('\n');
+
+            const { data: comments } = await github.rest.issues.listComments({
+              owner,
+              repo,
+              issue_number,
+              per_page: 100,
+            });
+            const previous = comments.find((comment) =>
+              comment.user?.type === 'Bot' && comment.body?.includes(marker)
+            );
+
+            if (previous) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: previous.id,
+                body,
+              });
+            }

DEPLOYMENT.md

@@ -39,6 +39,25 @@ This document explains the CI/CD pipeline and how to create releases.
 4. Uploads installers to the release
 5. Deploys web demo and download page to GitHub Pages
 
+### 3. PR Preview Workflows (`.github/workflows/build-preview.yml`, `.github/workflows/deploy-preview.yml`)
+
+**Triggers**: Pull Requests to `main` or `develop`, and completed PR preview builds
+
+**What they do**:
+1. Build the Emscripten web target for each open Pull Request
+2. Upload only the static preview files (`index.html`, JavaScript, WebAssembly, data, worker, and service worker files)
+3. Deploy the preview to GitHub Pages under `pr-previews/pr-<number>/`
+4. Post or update a PR comment with the live preview URL
+5. Remove the preview directory automatically when the PR is closed
+
+Preview URLs follow this format:
+
+```text
+https://amplitron.sudipmondal.co.in/pr-previews/pr-<number>/
+```
+
+The build and deploy steps are intentionally split across two workflows. Pull Request code is built with read-only permissions, while the Pages deployment workflow only publishes the generated artifact. This keeps preview deployments available for review without giving PR build scripts write access to the repository.
+
 ## Creating a Release
 
 ### Step 1: Prepare the Release
@@ -97,7 +116,7 @@ To trigger a release manually, push to `main` and let CI complete. The release w
 3. Branch: `gh-pages` / `root`
 4. Click Save
 
-The website will be available at: https://sudip-mondal-2002.github.io/Amplitron/
+The website will be available at: https://amplitron.sudipmondal.co.in/
 
 ### Update the Download Page