feat: add visual regression tests for kilo-ui with Playwright

- Add @playwright/test, playwright.config.ts (Chromium, 1280x720)
- Test file auto-discovers all stories from Storybook's index.json
- Screenshots cropped to #storybook-root, grouped per component
- CI workflow on Blacksmith with Storybook/Playwright/Bun caching
- Paths filter: only runs when kilo-ui or its deps change
- Auto-commits missing baselines back to the branch via CI
- Skips head-only (Font, Favicon) and non-deterministic (Typewriter) stories
- Documented in CONTRIBUTING.md

.github/workflows/visual-regression.yml

@@ -0,0 +1,100 @@
+name: Visual Regression Tests
+
+on:
+  pull_request:
+    paths:
+      - "packages/kilo-ui/**"
+      - "packages/ui/**"
+      - "packages/util/**"
+      - "packages/sdk/js/**"
+      - ".github/workflows/visual-regression.yml"
+
+jobs:
+  visual-regression:
+    name: Visual Regression (kilo-ui)
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          lfs: true
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.head_ref }}
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Cache Bun modules
+        uses: actions/cache@v4
+        with:
+          path: ~/.bun/install/cache
+          key: bun-${{ hashFiles('bun.lock') }}
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Cache Playwright browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ hashFiles('packages/kilo-ui/package.json') }}
+
+      - name: Install Playwright browsers
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: bunx playwright install chromium
+        working-directory: packages/kilo-ui
+
+      - name: Install Playwright system deps
+        run: bunx playwright install-deps chromium
+        working-directory: packages/kilo-ui
+
+      - name: Cache Storybook build
+        id: storybook-cache
+        uses: actions/cache@v4
+        with:
+          path: packages/kilo-ui/storybook-static
+          key: storybook-${{ hashFiles('packages/kilo-ui/src/**', 'packages/kilo-ui/.storybook/**', 'packages/ui/src/**') }}
+
+      - name: Build Storybook
+        if: steps.storybook-cache.outputs.cache-hit != 'true'
+        run: bun run build-storybook
+        working-directory: packages/kilo-ui
+
+      - name: Generate missing baselines and run visual regression tests
+        run: |
+          # Write any missing platform-specific baselines (new stories, first run on linux, etc.)
+          bun run test:visual:update
+          # Compare — runs against the files now on disk; will pass if rendering is stable
+          bun run test:visual
+        working-directory: packages/kilo-ui
+        env:
+          CI: true
+          PLAYWRIGHT_WORKERS: "4"
+
+      - name: Commit and push new baselines (if any)
+        # Run even if tests fail so we can inspect what changed
+        if: always()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add packages/kilo-ui/tests/visual-regression.spec.ts-snapshots/
+          if git diff --cached --quiet; then
+            echo "No new baselines — nothing to commit."
+          else
+            git commit -m "chore: add visual regression baselines for $(uname -s | tr '[:upper:]' '[:lower:]')"
+            git lfs push --all origin
+            git push
+          fi
+
+      - name: Upload test results on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: visual-regression-results
+          path: packages/kilo-ui/test-results/
+          retention-days: 7