add self-hosted visual regression pipeline

Storybook scenarios were not exercised in CI, and there was no
self-hosted screenshot baseline for catching unintended UI changes.
This left UI regressions dependent on manual review and an external
visual testing addon.

Switch Storybook testing to a self-hosted model by wiring a dedicated
storybook test project in Vitest and adding a Playwright visual suite
that snapshots stories tagged with `visual`. The visual runner builds
and serves static Storybook output, honors optional per-story
`parameters.visual` settings, disables motion for deterministic output,
and commits an initial baseline set for stable component stories.

The CI workflow now includes an isolated Storybook/visual job that
runs story execution separately from screenshot assertions and uploads
Playwright artifacts when diffs fail. Story fixtures that depended on
current time or randomness were made deterministic so baseline images
remain stable.

This adds initial coverage for the tagged Badge, TagInput, and JSON
stories through committed Playwright snapshots, and broad story
execution coverage through the Storybook Vitest project.

Author: bgentry

.github/workflows/ci.yaml

@@ -3,6 +3,7 @@ name: CI
 env:
   # Test database.
   TEST_DATABASE_URL: postgres://postgres:postgres@127.0.0.1:5432/river_test?sslmode=disable
+  NODE_VERSION: &node_version "24.14.1"
 
 on:
   push:
@@ -133,7 +134,7 @@ jobs:
     strategy:
       matrix:
         node-version:
-          - "22.18.0"
+          - *node_version
       fail-fast: false
     timeout-minutes: 5
 
@@ -170,7 +171,7 @@ jobs:
     strategy:
       matrix:
         node-version:
-          - "22.18.0"
+          - *node_version
       fail-fast: false
     timeout-minutes: 5
 
@@ -209,6 +210,62 @@ jobs:
         # Check tsc compilation even if there were linting issues:
         if: always()
 
+  js_storybook_and_visual:
+    name: Storybook and visual regression
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version:
+          - *node_version
+      fail-fast: false
+    timeout-minutes: 20
+
+    env:
+      NODE_ENV: test
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Install Node.js
+        uses: actions/setup-node@v6
+        with:
+          cache: "npm"
+          cache-dependency-path: package-lock.json
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm ci
+        shell: sh
+
+      - name: Install Playwright browser dependencies
+        run: npx playwright install --with-deps chromium
+
+      - name: Storybook story tests
+        run: npm run test-storybook
+
+      - name: Visual regression tests
+        run: npm run test-visual
+
+      - name: Upload Playwright HTML report
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          if-no-files-found: ignore
+          name: playwright-report
+          path: playwright-report/
+
+      - name: Upload Playwright test results
+        if: failure()
+        uses: actions/upload-artifact@v7
+        with:
+          if-no-files-found: ignore
+          name: playwright-test-results
+          path: test-results/
+
   release:
     name: Release
     permissions:
@@ -231,7 +288,7 @@ jobs:
         with:
           cache: "npm"
           cache-dependency-path: package-lock.json
-          node-version: "22.18.0"
+          node-version: ${{ env.NODE_VERSION }}
 
       - name: Install dependencies
         run: npm install

.storybook/main.ts

@@ -5,7 +5,7 @@ const config: StorybookConfig = {
     "@storybook/addon-links",
     "@storybook/addon-onboarding",
     "@storybook/addon-themes",
-    "@chromatic-com/storybook",
+    "@storybook/addon-vitest",
     "@storybook/addon-docs",
   ],
 

.storybook/preview.tsx

@@ -17,6 +17,7 @@ import type { Features } from "../src/services/features";
 import { FeaturesContext } from "../src/contexts/Features";
 import "../src/global-type-overrides";
 import "../src/index.css";
+import "../tests/visual/visual.css";
 import {
   $userSettings,
   clearAllSettings,
@@ -98,6 +99,28 @@ export const withSettings: Decorator = (StoryFn, context) => {
   return <StoryFn />;
 };
 
+const isVisualTestRun = () => {
+  if (typeof window === "undefined") {
+    return false;
+  }
+
+  return (
+    new URLSearchParams(window.location.search).get("visual-test") === "true"
+  );
+};
+
+export const withVisualTestingMode: Decorator = (StoryFn) => {
+  if (typeof document !== "undefined") {
+    if (isVisualTestRun()) {
+      document.documentElement.setAttribute("data-visual-test", "true");
+    } else {
+      document.documentElement.removeAttribute("data-visual-test");
+    }
+  }
+
+  return <StoryFn />;
+};
+
 // Define parameter types
 declare module "@storybook/react-vite" {
   interface Parameters {
@@ -108,11 +131,16 @@ declare module "@storybook/react-vite" {
       routes?: string[];
     };
     settings?: UserSettings;
+    visual?: {
+      viewport?: "desktop" | "mobile";
+      waitFor?: string;
+    };
   }
 }
 
 const preview: Preview = {
   decorators: [
+    withVisualTestingMode,
     withFeatures,
     withSettings,
     withRouter,

docs/README.md

@@ -82,3 +82,4 @@ By default logs are written with the [`slog.TextHandler`](https://pkg.go.dev/log
 ## Development
 
 See [developing River UI](./development.md).
+See [storybook visual regression](./visual_regression.md).

docs/visual_regression.md

@@ -0,0 +1,70 @@
+# Storybook Visual Regression
+
+River UI uses a self-hosted visual regression workflow based on Storybook and
+Playwright.
+
+## What runs in CI
+
+- `npm run test-storybook` runs Storybook stories with the Vitest addon so
+  rendering and interaction failures are caught.
+- `npm run test-visual` runs Playwright screenshot assertions against a built
+  static Storybook.
+- Visual baseline rendering is standardized on Linux Chromium.
+
+## Marking stories for visual snapshots
+
+Only stories tagged with `visual` are screenshot-tested.
+
+```ts
+export const Example: Story = {
+  tags: ["visual"],
+};
+```
+
+Stories without this tag still run in `test-storybook`, but they are skipped by
+`test-visual`.
+
+## Optional visual parameters
+
+Stories can define an optional `parameters.visual` contract:
+
+```ts
+parameters: {
+  visual: {
+    viewport: "mobile",
+    waitFor: "[data-testid='ready']",
+  },
+}
+```
+
+- `viewport`: `desktop` (default) or `mobile`.
+- `waitFor`: CSS selector to wait for before screenshotting.
+
+## Writing screenshot-safe stories
+
+To keep baselines stable:
+
+- Avoid `Date.now()`, `new Date()`, random values, and faker defaults unless
+  you pass fixed values.
+- Avoid async timing behavior unless there is a deterministic `waitFor`
+  selector.
+- Prefer static fixtures with explicit timestamps and IDs.
+
+## Local workflow
+
+- Run story execution tests: `npm run test-storybook`
+- Run visual tests: `npm run test-visual`
+- Update visual baselines intentionally: `npm run test-visual:update`
+
+Updated snapshots are written next to the visual test spec under Playwright's
+snapshot directory.
+
+## Debugging CI failures
+
+When visual regression fails, CI uploads Playwright artifacts:
+
+- `playwright-report/` (HTML report)
+- `test-results/` (diff images and failure diagnostics)
+
+Use those artifacts to inspect unexpected changes, then either fix regressions
+or intentionally update snapshots.