test(visual): establish deployment preview screenshot baselines

.github/workflows/visual-regression.yml

@@ -0,0 +1,33 @@
+name: Visual Regression Baseline Check
+
+on:
+  pull_request:
+    paths:
+      - 'apps/backend/tests/visual/**'
+      - '.github/workflows/visual-regression.yml'
+  push:
+    branches:
+      - main
+    paths:
+      - 'apps/backend/tests/visual/**'
+      - '.github/workflows/visual-regression.yml'
+
+jobs:
+  compare-baselines:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Compare deployment preview visual baselines
+        run: npm run --workspace @craft/backend test -- tests/visual/preview.visual.test.ts

.gitignore

@@ -38,6 +38,7 @@ next-env.d.ts
 # Exclude markdown files except design.md and README.md
 *.md
 !README.md
+!CONTRIBUTING.md
 !design.md
 !.craft/specs/craft-platform/design.md
 !docs/*.md

CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+This repository uses a monorepo layout (`apps/*`, `packages/*`) with tests and linting enforced before merge.
+
+## General Workflow
+
+1. Create a focused branch for your issue.
+2. Keep changes scoped and reviewable.
+3. Add or update tests with behavior changes.
+4. Run checks locally before opening a PR:
+
+```bash
+npm run test
+npm run lint
+npm run build
+```
+
+5. Link the PR to the relevant issue.
+
+## Visual Regression Baselines (Deployment Preview)
+
+Visual regression baselines for deployment preview templates are stored in:
+
+- `apps/backend/tests/visual/baselines/deployment-preview/dex.baseline.json`
+- `apps/backend/tests/visual/baselines/deployment-preview/defi.baseline.json`
+- `apps/backend/tests/visual/baselines/deployment-preview/payment.baseline.json`
+- `apps/backend/tests/visual/baselines/deployment-preview/asset.baseline.json`
+
+### Compare Baselines
+
+Run this in default mode to validate that generated screenshots remain within the allowed diff threshold:
+
+```bash
+npm run --workspace @craft/backend test -- tests/visual/preview.visual.test.ts
+```
+
+CI runs the same compare path in `.github/workflows/visual-regression.yml`. Any diff over threshold fails the job.
+
+### Update Baselines
+
+When intentional visual changes are made to deployment preview templates, regenerate and commit updated baselines:
+
+```bash
+VISUAL_BASELINE_MODE=store npm run --workspace @craft/backend test -- tests/visual/preview.visual.test.ts
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:VISUAL_BASELINE_MODE='store'
+npm run --workspace @craft/backend test -- tests/visual/preview.visual.test.ts
+Remove-Item Env:VISUAL_BASELINE_MODE
+```
+
+### PR Expectations
+
+1. Include before/after screenshots for each affected template category (`dex`, `defi`, `payment`, `asset`).
+2. Keep baseline-only updates in small, reviewable commits.
+3. Ensure baseline-missing failures are not bypassed; tests should fail with a clear missing-baseline message.

apps/backend/tests/visual/baselines/deployment-preview/asset.baseline.json

@@ -0,0 +1,17 @@
+{
+  "category": "asset",
+  "templateId": "asset-issuance",
+  "customization": {
+    "branding": {
+      "primaryColor": "#34C759"
+    },
+    "features": {
+      "enableClawback": false
+    }
+  },
+  "viewport": {
+    "width": 1920,
+    "height": 1080
+  },
+  "screenshotBase64": "cZNn7WFzc2V0LWlzc3VhbmNlAAAAAAAAAAAAAAAAAAB7InRlbXBsYXRlSWQiOiJhc3NldC1pc3N1YW5jZSIsImN1c3RvbWl6YXRpb24iOnsiYnJhbmRpbmciOnsicHJpbWFyeUNvbG9yIjoiIzM0Qzc1OSJ9LCJmZWF0dXJlcyI6eyJlbmFibGVDbGF3YmFjayI6ZmFsc2V9fSwidmlld3BvcnQiOnsid2lkdGgiOjE5MjAsImhlaWdodCI6MTA4MH19AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+}

apps/backend/tests/visual/baselines/deployment-preview/defi.baseline.json

@@ -0,0 +1,17 @@
+{
+  "category": "defi",
+  "templateId": "soroban-defi",
+  "customization": {
+    "branding": {
+      "logo": "https://example.com/logo.png"
+    },
+    "features": {
+      "enableLiquidityPools": true
+    }
+  },
+  "viewport": {
+    "width": 1920,
+    "height": 1080
+  },
+  "screenshotBase64": "BaX1MXNvcm9iYW4tZGVmaQAAAAAAAAAAAAAAAAAAAAB7InRlbXBsYXRlSWQiOiJzb3JvYmFuLWRlZmkiLCJjdXN0b21pemF0aW9uIjp7ImJyYW5kaW5nIjp7ImxvZ28iOiJodHRwczovL2V4YW1wbGUuY29tL2xvZ28ucG5nIn0sImZlYXR1cmVzIjp7ImVuYWJsZUxpcXVpZGl0eVBvb2xzIjp0cnVlfX0sInZpZXdwb3J0Ijp7IndpZHRoIjoxOTIwLCJoZWlnaHQiOjEwODB9fQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+}

apps/backend/tests/visual/baselines/deployment-preview/dex.baseline.json

@@ -0,0 +1,19 @@
+{
+  "category": "dex",
+  "templateId": "stellar-dex",
+  "customization": {
+    "branding": {
+      "primaryColor": "#000000",
+      "secondaryColor": "#FFFFFF"
+    },
+    "features": {
+      "enableCharts": true,
+      "enableHistory": true
+    }
+  },
+  "viewport": {
+    "width": 1920,
+    "height": 1080
+  },
+  "screenshotBase64": "DC/RYHN0ZWxsYXItZGV4AAAAAAAAAAAAAAAAAAAAAAB7InRlbXBsYXRlSWQiOiJzdGVsbGFyLWRleCIsImN1c3RvbWl6YXRpb24iOnsiYnJhbmRpbmciOnsicHJpbWFyeUNvbG9yIjoiIzAwMDAwMCIsInNlY29uZGFyeUNvbG9yIjoiI0ZGRkZGRiJ9LCJmZWF0dXJlcyI6eyJlbmFibGVDaGFydHMiOnRydWUsImVuYWJsZUhpc3RvcnkiOnRydWV9fSwidmlld3BvcnQiOnsid2lkdGgiOjE5MjAsImhlaWdodCI6MTA4MH19AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+}

apps/backend/tests/visual/baselines/deployment-preview/payment.baseline.json

@@ -0,0 +1,17 @@
+{
+  "category": "payment",
+  "templateId": "payment-gateway",
+  "customization": {
+    "branding": {
+      "primaryColor": "#007AFF"
+    },
+    "features": {
+      "enableInvoicing": true
+    }
+  },
+  "viewport": {
+    "width": 1920,
+    "height": 1080
+  },
+  "screenshotBase64": "Sftt3HBheW1lbnQtZ2F0ZXdheQAAAAAAAAAAAAAAAAB7InRlbXBsYXRlSWQiOiJwYXltZW50LWdhdGV3YXkiLCJjdXN0b21pemF0aW9uIjp7ImJyYW5kaW5nIjp7InByaW1hcnlDb2xvciI6IiMwMDdBRkYifSwiZmVhdHVyZXMiOnsiZW5hYmxlSW52b2ljaW5nIjp0cnVlfX0sInZpZXdwb3J0Ijp7IndpZHRoIjoxOTIwLCJoZWlnaHQiOjEwODB9fQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+}