fix: verify WebAssembly deployments before publishing

.github/workflows/ci.yml

@@ -6,6 +6,12 @@ on:
   pull_request:
     branches: [ main, dev ]
 
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
 
 env:
   CARGO_TERM_COLOR: always
@@ -35,3 +41,130 @@ jobs:
 
       - name: Run Test Suite
         run: cargo test --all
+
+  build-and-smoke-test:
+    name: Build & Launch WebAssembly Bundle
+    needs: check-and-test
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v7
+
+      - name: Setup Rust Toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: wasm32-unknown-unknown
+
+      - name: Cache Cargo Dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install Smoke Test Dependencies
+        run: npm ci
+
+      - name: Install Binaryen and Trunk
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y binaryen
+          trunk_archive="trunk-x86_64-unknown-linux-gnu.tar.gz"
+          trunk_release="https://github.com/trunk-rs/trunk/releases/download/v0.21.5"
+          wget --quiet "$trunk_release/$trunk_archive" --directory-prefix /tmp
+          wget --quiet "$trunk_release/$trunk_archive.sha256" --directory-prefix /tmp
+          pushd /tmp
+          sha256sum --check "$trunk_archive.sha256"
+          popd
+          sudo tar -xzf "/tmp/$trunk_archive" -C /usr/local/bin
+          trunk --version
+
+      - name: Build WebAssembly Release Bundle
+        run: trunk build --release --public-url "./"
+
+      - name: Stamp Built Revision
+        env:
+          DEPLOY_SHA: ${{ github.sha }}
+        run: npm run stamp:wasm
+
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Smoke Test WebAssembly Startup
+        env:
+          EXPECTED_DEPLOY_SHA: ${{ github.sha }}
+        run: npm run test:wasm-smoke
+
+      - name: Upload GitHub Pages Artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: ./dist
+
+      - name: Upload Smoke Test Failure Screenshot
+        if: failure()
+        uses: actions/upload-artifact@v5
+        with:
+          name: wasm-smoke-test-failure
+          path: test-results/
+          if-no-files-found: ignore
+
+  deploy:
+    name: Deploy Tested Bundle
+    needs: build-and-smoke-test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    outputs:
+      page_url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+
+  verify-live-site:
+    name: Launch Published WebAssembly App
+    needs: deploy
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v7
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: npm
+
+      - name: Install Smoke Test Dependencies
+        run: npm ci
+
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Launch Published WebAssembly App
+        env:
+          EXPECTED_DEPLOY_SHA: ${{ github.sha }}
+          SMOKE_BASE_URL: ${{ needs.deploy.outputs.page_url }}
+        run: npm run test:wasm-smoke
+
+      - name: Upload Live Smoke Test Failure Screenshots
+        if: failure()
+        uses: actions/upload-artifact@v5
+        with:
+          name: live-wasm-smoke-test-failure
+          path: test-results/
+          if-no-files-found: ignore

.gitignore

@@ -12,3 +12,9 @@ releases/
 # Trunk build output
 /dist
 
+# Web smoke test output
+/node_modules
+/playwright-browsers
+/test-results
+/.npm-cache
+

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- Fixed GitHub Pages releases to run directly from `main` after the native quality gates, require a successful browser launch test before deployment, and launch the published commit in a second live-site check.
+
 ## [0.9.0] - 2026-08-10
 
 ### Added

CONTRIBUTING.md

@@ -33,7 +33,7 @@ Contributions generally fall into three categories:
 
 - A [stable Rust toolchain](https://www.rust-lang.org/tools/install), including `rustfmt` and Clippy. The crate uses the Rust 2021 edition.
 - Git
-- For optional WebAssembly work: Trunk and the `wasm32-unknown-unknown` Rust target
+- For WebAssembly, browser-startup, or hosting changes: Node.js 20 or newer, npm, Trunk 0.21.5, and the `wasm32-unknown-unknown` Rust target
 
 ### Development Setup
 
@@ -58,6 +58,27 @@ Contributions generally fall into three categories:
    cargo clippy --all-targets -- -D warnings
    ```
 
+### WebAssembly Launch Test
+
+Pull requests and pushes to `dev` or `main` run a browser launch test in CI. If
+your change affects WebAssembly startup, `index.html`, GitHub Actions, or hosting,
+run the same check locally:
+
+```text
+rustup target add wasm32-unknown-unknown
+npm ci
+npx playwright install chromium
+trunk build --release --public-url ./
+npm run stamp:wasm
+npm run test:wasm-smoke
+```
+
+The smoke test serves the generated bundle at the same `/AlgoBuddy/` subpath
+used by GitHub Pages. It verifies the JavaScript and WebAssembly responses,
+WebAssembly MIME type, rendered-app readiness, and the bundle's Git revision.
+`npm run stamp:wasm` reads the current commit from Git when `DEPLOY_SHA` is not
+set, and the local smoke test reads that revision from the generated bundle.
+
 ---
 
 ## Architecture & Engine
@@ -110,7 +131,7 @@ Maintainers follow the same review path as other contributors for normal develop
 - Reserve direct commits to `dev` for coordinated release-candidate assembly or narrowly scoped fixes required to complete the release checks. Run the complete release check before pushing that candidate.
 - Treat `main` as the production branch. Do not commit or push directly to `main`; promote releases only through a reviewed Pull Request from `dev`.
 - Do not rewrite the shared history of `dev` or `main`.
-- Wait for CI and CodeQL to pass before merging. Release Pull Requests must also satisfy the version, changelog, native-build, and WebAssembly-build requirements in [RELEASING.md](RELEASING.md).
+- Wait for CI and CodeQL to pass before merging. CI now runs the native quality gates before its WebAssembly launch test. A `main` deployment uses that exact tested bundle and then launches the published site in a second browser check. Release Pull Requests must also satisfy the version, changelog, native-build, and WebAssembly-build requirements in [RELEASING.md](RELEASING.md).
 
 ---
 
@@ -121,6 +142,7 @@ Before submitting a Pull Request, ensure your changes adhere to these requiremen
 - **Formatting**: Run `cargo fmt --all -- --check` to verify standard Rust formatting.
 - **Clippy Clean**: Run `cargo clippy --all-targets -- -D warnings` to verify zero warnings.
 - **Unit Tests**: Add unit tests for any new algorithm step generators or parser functions.
+- **WebAssembly Startup**: For changes to the web entry point, loader, build workflow, or hosting behavior, run the WebAssembly launch test documented above.
 - **Synchronized State**: Keep timeline descriptions, inspector values, canvas state, final results, and highlighted source lines consistent at every step.
 - **Plain Text Interface**: Do not add decorative emoji to UI labels, documentation, code comments, contributor templates, or release notes. A functional text symbol may represent an established control state, such as `★`/`☆` for favorites, when the control also provides a clear tooltip.
 - **Commit Messages**: Write concise, descriptive commit messages (e.g., `feat: add visualizer for problem #X`, `fix: resolve bounds checking on timeline scrubber`).

RELEASING.md

@@ -17,17 +17,19 @@ directly on `main`.
    ./scripts/release-check.ps1 -ExpectedVersion X.Y.Z -RequireClean
    ```
 
-6. Smoke-test the native application and the generated `dist` bundle. Verify
-   navigation, custom input, Play/Pause, Prev/Next, scrub, Reset, and every
-   visualizer repaired by the release.
+6. Run the browser launch test documented in `CONTRIBUTING.md`, then smoke-test
+   the native application. Verify navigation, custom input, Play/Pause,
+   Prev/Next, scrub, Reset, and every visualizer repaired by the release.
 7. Push `dev` and wait for CI and CodeQL to pass on the candidate commit.
 
 ## Publish
 
 1. Open a release pull request from `dev` to `main` using the changelog as its
    summary.
 2. Merge only after required checks pass.
-3. Verify the GitHub Pages deployment and live demo.
+3. Verify `CI & Quality Gates` completed its native gates, launched the local
+   WebAssembly bundle, deployed that tested artifact, and launched the published
+   GitHub Pages site at the expected commit revision.
 4. Create and push annotated tag `vX.Y.Z` on the exact merged `main` commit.
 5. Verify that the tag workflow publishes a GitHub Release from the matching
    changelog section.

index.html

@@ -60,7 +60,7 @@
     </script>
 </head>
 <body>
-    <canvas id="the_canvas_id"></canvas>
+    <canvas id="the_canvas_id" data-algobuddy-ready="false"></canvas>
     <div id="loading_text" class="loading-container">
         <div class="spinner"></div>
         <h2 style="margin: 0; font-size: 20px; color: #569cd6;">Loading AlgoBuddy...</h2>

package.json

@@ -0,0 +1,14 @@
+{
+  "name": "algobuddy-web-smoke",
+  "private": true,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "stamp:wasm": "node scripts/stamp-wasm-build.mjs",
+    "test:wasm-smoke": "node scripts/wasm-smoke.mjs"
+  },
+  "devDependencies": {
+    "playwright": "1.62.1"
+  }
+}