diff --git a/.gitea/workflows/playwright-install.yml b/.gitea/workflows/playwright-install.yml
new file mode 100644
index 00000000..6a9f19ac
--- /dev/null
+++ b/.gitea/workflows/playwright-install.yml
@@ -0,0 +1,180 @@
+# playwright-install.yml — Install Playwright for visual smoke tests
+# Refs: Issue #561, PR #558 (nexus_smoke_test.py)
+#
+# Installs Playwright and Chromium for visual smoke tests.
+# Can be reused by other workflows that need browser automation.
+
+name: Install Playwright
+
+on:
+  # Run when called by other workflows
+  workflow_call:
+    inputs:
+      install_chromium:
+        description: 'Install Chromium browser'
+        required: false
+        default: true
+        type: boolean
+      install_deps:
+        description: 'Install system dependencies'
+        required: false
+        default: true
+        type: boolean
+  
+  # Run on push to main when Playwright files change
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/**/nexus_smoke_test.py'
+      - 'scripts/**/*playwright*'
+      - '.gitea/workflows/playwright-install.yml'
+  
+  # Run on PRs that touch Playwright files
+  pull_request:
+    paths:
+      - 'scripts/**/nexus_smoke_test.py'
+      - 'scripts/**/*playwright*'
+      - '.gitea/workflows/playwright-install.yml'
+
+jobs:
+  install-playwright:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install Python dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install playwright
+      
+      - name: Install Playwright browsers
+        if: inputs.install_chromium
+        run: |
+          playwright install chromium
+          playwright install-deps chromium
+      
+      - name: Install system dependencies
+        if: inputs.install_deps
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libnss3 \
+            libnspr4 \
+            libatk1.0-0 \
+            libatk-bridge2.0-0 \
+            libcups2 \
+            libdrm2 \
+            libxkbcommon0 \
+            libxcomposite1 \
+            libxdamage1 \
+            libxfixes3 \
+            libxrandr2 \
+            libgbm1 \
+            libpango-1.0-0 \
+            libcairo2 \
+            libasound2 \
+            libatspi2.0-0 \
+            libwayland-client0
+      
+      - name: Verify Playwright installation
+        run: |
+          python -c "import playwright; print(f'Playwright version: {playwright.__version__}')"
+          python -c "from playwright.sync_api import sync_playwright; print('Playwright API imported successfully')"
+          playwright --version
+      
+      - name: Test Chromium launch
+        if: inputs.install_chromium
+        run: |
+          python -c "
+          from playwright.sync_api import sync_playwright
+          with sync_playwright() as p:
+              browser = p.chromium.launch()
+              page = browser.new_page()
+              page.goto('data:text/html,<h1>Test</h1>')
+              print(f'Page title: {page.title()}')
+              browser.close()
+              print('Chromium launched and closed successfully')
+          "
+      
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ hashFiles('**/playwright-install.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-playwright-
+      
+      - name: Output installation info
+        run: |
+          echo "Playwright installation completed"
+          echo "Python version: $(python --version)"
+          echo "Playwright version: $(playwright --version)"
+          echo "Cache directory: ~/.cache/ms-playwright"
+          if [ -d ~/.cache/ms-playwright ]; then
+            echo "Cached browsers:"
+            ls -la ~/.cache/ms-playwright
+          fi
+
+  # Job to test Nexus smoke test with Playwright
+  test-nexus-smoke:
+    needs: install-playwright
+    runs-on: ubuntu-latest
+    
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+      
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install playwright Pillow
+          playwright install chromium
+          playwright install-deps chromium
+      
+      - name: Test Nexus smoke test script
+        run: |
+          if [ -f "scripts/nexus_smoke_test.py" ]; then
+            echo "Testing nexus_smoke_test.py..."
+            python scripts/nexus_smoke_test.py --help
+            echo "Script is executable"
+          else
+            echo "nexus_smoke_test.py not found, skipping test"
+          fi
+      
+      - name: Test Playwright integration
+        run: |
+          python -c "
+          import sys
+          sys.path.insert(0, 'scripts')
+          try:
+              # Try to import the smoke test module
+              from nexus_smoke_test import NexusSmokeTest
+              print('Successfully imported NexusSmokeTest')
+              
+              # Test Playwright initialization
+              test = NexusSmokeTest()
+              print('NexusSmokeTest initialized successfully')
+          except ImportError as e:
+              print(f'Import error: {e}')
+              print('This is expected if nexus_smoke_test.py does not exist yet')
+          except Exception as e:
+              print(f'Error: {e}')
+          "