feat(ui-scripts): add a live HTML view to the visual-diff report

The lightbox gains an HTML mode alongside Baseline/Actual/Diff/Slider that iframes the live
rendered page, so a reviewer can inspect the real DOM, computed styles, and text next to the
pixels. The page URL is derived from the screenshot name via the existing meta map and facet
suffixes (appUrlFor), and shown only when the page still exists and the app was published.

To back it, CI rebuilds the regression-test app as a static export with a basePath matching its
published location and drops it next to the report; visual-diff is passed --app-path app. The
basePath is env-driven (REGRESSION_APP_BASE_PATH) so local dev and the Cypress capture build are
unaffected.

Published reports previously accumulated on gh-pages forever, and shipping the app bundle per PR
makes that worse, so the workflow now also removes a PR's report directory when the PR closes.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: balzss

.github/workflows/visual-regression.yml

@@ -1,6 +1,10 @@
 name: Visual regression
 
-on: [pull_request]
+on:
+  pull_request:
+    # `closed` is included so the cleanup job can remove the PR's published
+    # report from gh-pages; the capture job skips the `closed` event.
+    types: [opened, synchronize, reopened, closed]
 
 concurrency:
   group: gh-pages
@@ -9,6 +13,7 @@ concurrency:
 jobs:
   visual-regression:
     name: Capture, diff, and publish report
+    if: github.event.action != 'closed'
     runs-on: ubuntu-latest
     container:
       image: cypress/browsers:latest
@@ -86,6 +91,20 @@ jobs:
           --meta cypress/meta.json
           --source-base-url https://github.com/${{ github.repository }}/blob/${{ github.head_ref }}/regression-test/src/app
           --facets canvas,light,dark
+          --app-path app
+        continue-on-error: true
+
+      # Rebuild the app with a basePath matching its published location, then
+      # drop it next to the report so the report's "HTML" view can iframe the
+      # live rendered page. Best-effort: a build hiccup must not block the report
+      # (the HTML view would just 404 for that run).
+      - name: Build and bundle app for the report's HTML view
+        working-directory: regression-test
+        env:
+          REGRESSION_APP_BASE_PATH: /visual-regression/pr-${{ github.event.pull_request.number }}/app
+        run: |
+          npm run build
+          cp -r out .report/app
         continue-on-error: true
 
       - name: Publish report to gh-pages
@@ -159,3 +178,30 @@ jobs:
       - name: Fail if regressions or Cypress failed
         if: steps.diff.outcome == 'failure' || steps.cypress.outcome == 'failure'
         run: exit 1
+
+  cleanup-report:
+    name: Remove report when PR closes
+    if: github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: gh-pages
+          fetch-depth: 0
+      - name: Remove this PR's report directory
+        run: |
+          DIR="visual-regression/pr-${{ github.event.pull_request.number }}"
+          if [ ! -d "$DIR" ]; then
+            echo "No report directory ($DIR); nothing to remove."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git rm -rq "$DIR"
+          git commit -m "visual-regression: remove report for closed PR #${{ github.event.pull_request.number }}"
+          # gh-pages is written by several workflows; rebase before pushing in
+          # case it moved since checkout.
+          git pull --rebase origin gh-pages
+          git push

docs/contributing/testing/visual-regression.md

@@ -70,6 +70,8 @@ open .report/index.html
 | `--pr-url <url>`                                               | —                     | Target of the PR link.                                                                                                                                                     |
 | `--meta <file>`                                                | —                     | JSON mapping screenshot slug → visited URL path. Enables per-row source-file links in the report. Produced automatically by `spec.cy.ts` via `cy.task('recordMeta', ...)`. |
 | `--source-base-url <url>`                                      | —                     | GitHub blob URL of `regression-test/src/app` on the branch being reviewed. Combined with `--meta` to build links like `treebrowser/page.tsx`.                              |
+| `--facets <list>`                                              | —                     | Comma-separated facet suffixes (e.g. `canvas,light,dark`) rendered as one-click filter chips that match screenshots named `<name>-<facet>`.                                |
+| `--app-path <path>`                                            | —                     | Path, relative to the report root, where a static export of the app is published (CI uses `app`). Enables the lightbox **HTML** view, which iframes the live rendered page. |
 
 ### Interpreting the report
 
@@ -82,6 +84,7 @@ Top-bar controls:
 - **Lightbox** — click any thumbnail to open a fullscreen viewer. Inside:
   - `Baseline`, `Actual`, `Diff` buttons switch between the three images.
   - `Slider` mode overlays baseline and actual with a drag handle so you can scrub the boundary back and forth.
+  - `HTML` mode iframes the live rendered page (a static export of the app published next to the report) so you can inspect the real DOM, computed styles, and text alongside the pixels. Shown only when the page still exists and the app was published (`--app-path`).
   - `1:1` / `Fit` toggles between native pixel size (scrollable) and fit-to-window.
   - `‹` / `›` step through visible rows (respects the current filter).
 

packages/ui-scripts/lib/__node_tests__/visual-diff.test.ts

@@ -28,6 +28,7 @@ import {
   thumb,
   indexByName,
   sourceLinkFor,
+  appUrlFor,
   boxesFromMask
 } from '../commands/visual-diff.ts'
 
@@ -172,6 +173,45 @@ describe('sourceLinkFor', () => {
   })
 })
 
+describe('appUrlFor', () => {
+  const facets = ['canvas', 'light', 'dark']
+  const meta = { 'button-dark': '/button', 'small-components-light': '/small-components' }
+
+  it('returns an empty string when appPath is not provided', () => {
+    expect(appUrlFor('button-dark.png', meta, facets)).toBe('')
+  })
+
+  it('returns an empty string when meta is null', () => {
+    expect(appUrlFor('button-dark.png', null, facets, 'app')).toBe('')
+  })
+
+  it('returns an empty string when meta has no entry for the screenshot', () => {
+    expect(appUrlFor('unknown-dark.png', meta, facets, 'app')).toBe('')
+  })
+
+  it('builds a relative app URL with the theme query from the trailing facet', () => {
+    expect(appUrlFor('button-dark.png', meta, facets, 'app')).toBe(
+      'app/button/?theme=dark'
+    )
+  })
+
+  it('matches facets even when the slug itself contains hyphens', () => {
+    expect(appUrlFor('small-components-light.png', meta, facets, 'app')).toBe(
+      'app/small-components/?theme=light'
+    )
+  })
+
+  it('omits the theme query when no facet matches the name', () => {
+    expect(appUrlFor('button-dark.png', meta, [], 'app')).toBe('app/button/')
+  })
+
+  it('strips a trailing slash from appPath', () => {
+    expect(appUrlFor('button-dark.png', meta, facets, 'app/')).toBe(
+      'app/button/?theme=dark'
+    )
+  })
+})
+
 describe('boxesFromMask', () => {
   it('returns no boxes for an unchanged mask', () => {
     expect(boxesFromMask(mask(32, 32, []), 32, 32)).toEqual([])

packages/ui-scripts/lib/commands/visual-diff.ts

@@ -54,6 +54,7 @@ type Args = {
   meta?: string
   sourceBaseUrl?: string
   facets?: string
+  appPath?: string
 }
 
 type Meta = Record<string, string>
@@ -73,6 +74,37 @@ export function sourceLinkFor(
   return `<a class="source-link" href="${url}" target="_blank" rel="noopener">${display}</a>`
 }
 
+/**
+ * Build the URL of the live rendered page for a screenshot, relative to the
+ * report root. The app (a static export of the regression-test Next app) is
+ * published under `appPath` next to the report, so a screenshot named
+ * `<slug>-<theme>.png` maps to `<appPath><pagePath>/?theme=<theme>` — e.g.
+ * `app/button/?theme=dark`. Returns '' when the app wasn't published, meta is
+ * missing, or the page path can't be resolved (the HTML view is then hidden).
+ *
+ * `meta` is keyed by the full screenshot name (minus `.png`), e.g.
+ * `button-dark → /button`; the theme is recovered by matching the name's
+ * trailing `-<facet>` against the known facets (facets may themselves contain
+ * hyphens, so a plain split won't do).
+ *
+ * @internal — exported only for tests; not part of the package's public API.
+ */
+export function appUrlFor(
+  name: string,
+  meta: Meta | null,
+  facets: string[],
+  appPath?: string
+): string {
+  if (!appPath || !meta) return ''
+  const slug = name.replace(/\.png$/, '')
+  const pagePath = meta[slug]
+  if (!pagePath) return ''
+  const facet = facets.find((f) => slug.endsWith('-' + f))
+  const base = appPath.replace(/\/$/, '')
+  const query = facet ? `?theme=${facet}` : ''
+  return `${base}${pagePath}/${query}`
+}
+
 function walk(dir: string): string[] {
   if (!existsSync(dir)) return []
   const out: string[] = []
@@ -282,7 +314,13 @@ export function thumb(mode: string, name: string): string {
   return `<img loading="lazy" src="${mode}/${name}" data-name="${name}" data-mode="${mode}" class="thumb" />`
 }
 
-function row(r: Result, meta: Meta | null, sourceBaseUrl?: string): string {
+function row(
+  r: Result,
+  meta: Meta | null,
+  sourceBaseUrl?: string,
+  facets: string[] = [],
+  appPath?: string
+): string {
   const b = r.status === 'added' ? '' : thumb('baseline', r.name)
   const a = r.status === 'removed' ? '' : thumb('actual', r.name)
   const d = r.status === 'changed' ? thumb('diff', r.name) : ''
@@ -294,10 +332,15 @@ function row(r: Result, meta: Meta | null, sourceBaseUrl?: string): string {
       : ''
   const source = sourceLinkFor(r.name, meta, sourceBaseUrl)
   const hasBoth = r.status === 'changed' || r.status === 'unchanged'
+  // A 'removed' screenshot has no current page to render, so offer the live
+  // HTML view only when the page still exists (added/changed/unchanged).
+  const htmlUrl =
+    r.status === 'removed' ? '' : appUrlFor(r.name, meta, facets, appPath)
+  const htmlAttr = htmlUrl ? ` data-html-url="${htmlUrl}"` : ''
   return `
     <section class="row" data-status="${r.status}" data-name="${
       r.name
-    }" data-has-both="${hasBoth}">
+    }" data-has-both="${hasBoth}"${htmlAttr}>
       <header><h2>${r.name}</h2>${badgeFor(
         r.status
       )}${pixelMeta}${source}</header>
@@ -312,7 +355,8 @@ function renderHtml(
   prUrl?: string,
   meta?: Meta | null,
   sourceBaseUrl?: string,
-  facets: string[] = []
+  facets: string[] = [],
+  appPath?: string
 ): string {
   const prBadge =
     prNumber && prUrl
@@ -360,6 +404,7 @@ function renderHtml(
   .lightbox .viewer.actual-size { align-items: flex-start; }
   .lightbox .viewer > img { display: block; background: #fff; max-width: 100%; max-height: 100%; object-fit: contain; }
   .lightbox .viewer.actual-size > img { max-width: none; max-height: none; image-rendering: pixelated; }
+  .lightbox .viewer > iframe { width: 100%; height: 100%; border: 0; background: #fff; }
   .lightbox .slider { position: relative; user-select: none; background: #fff; flex-shrink: 0; }
   .lightbox .slider img { position: absolute; inset: 0; width: 100%; height: 100%; display: block; }
   .lightbox .slider .top { clip-path: inset(0 0 0 var(--split, 50%)); }
@@ -398,7 +443,7 @@ function renderHtml(
     }
   </header>
   <main>${results
-    .map((r) => row(r, meta ?? null, sourceBaseUrl))
+    .map((r) => row(r, meta ?? null, sourceBaseUrl, facets, appPath))
     .join('')}</main>
 
   <div class="lightbox" id="lb" aria-hidden="true">
@@ -409,6 +454,7 @@ function renderHtml(
         <button data-mode="actual">Actual</button>
         <button data-mode="diff">Diff</button>
         <button data-mode="slider" id="lb-slider-btn">Slider</button>
+        <button data-mode="html" id="lb-html-btn">HTML</button>
       </div>
       <button id="lb-zoom">1:1</button>
       <button id="lb-prev" aria-label="Previous">‹</button>
@@ -462,6 +508,7 @@ function renderHtml(
       const lbTitle = document.getElementById('lb-title')
       const lbViewer = document.getElementById('lb-viewer')
       const lbSliderBtn = document.getElementById('lb-slider-btn')
+      const lbHtmlBtn = document.getElementById('lb-html-btn')
       const lbZoomBtn = document.getElementById('lb-zoom')
       const state = { rows: [], idx: 0, mode: 'diff', zoom: false }
 
@@ -481,8 +528,10 @@ function renderHtml(
         const name = row.dataset.name
         const status = row.dataset.status
         const hasBoth = row.dataset.hasBoth === 'true'
+        const htmlUrl = row.dataset.htmlUrl || ''
         lbTitle.textContent = name + '  (' + (state.idx + 1) + '/' + state.rows.length + ') · ' + status
         lbSliderBtn.style.display = hasBoth ? '' : 'none'
+        lbHtmlBtn.style.display = htmlUrl ? '' : 'none'
 
         document.querySelectorAll('#lb-modes button').forEach(b => {
           b.classList.toggle('active', b.dataset.mode === state.mode)
@@ -492,7 +541,8 @@ function renderHtml(
           baseline: status !== 'added',
           actual: status !== 'removed',
           diff: status === 'changed',
-          slider: hasBoth
+          slider: hasBoth,
+          html: !!htmlUrl
         }
         if (!availableModes[state.mode]) state.mode = availableModes.diff ? 'diff' : (availableModes.actual ? 'actual' : 'baseline')
 
@@ -543,6 +593,8 @@ function renderHtml(
           window.addEventListener('mouseup', () => { dragging = false })
           wrap.addEventListener('touchstart', (e) => { onMove(e); e.preventDefault() }, { passive: false })
           wrap.addEventListener('touchmove', (e) => { onMove(e); e.preventDefault() }, { passive: false })
+        } else if (state.mode === 'html') {
+          lbViewer.innerHTML = '<iframe src="' + htmlUrl + '" title="' + name + '"></iframe>'
         } else {
           lbViewer.innerHTML = '<img src="' + state.mode + '/' + name + '" alt="' + name + '" />'
         }
@@ -682,7 +734,8 @@ function run(args: Args): number {
       args.prUrl,
       meta,
       args.sourceBaseUrl,
-      facets
+      facets,
+      args.appPath
     )
   )
 
@@ -747,6 +800,11 @@ export default {
       type: 'string',
       describe:
         'Comma-separated facet suffixes (e.g. "canvas,light,dark") rendered as one-click filter chips that match screenshots named "<name>-<facet>"'
+    },
+    'app-path': {
+      type: 'string',
+      describe:
+        'Path (relative to the report root) where the live app is published, e.g. "app". Enables an "HTML" view in the lightbox that iframes the rendered page for each screenshot.'
     }
   },
   handler: (argv: Args) => {

regression-test/README.md

@@ -2,7 +2,7 @@
 
 A small Next.js app that imports `@instructure/ui` locally and exposes one page per component. Cypress visits each page to:
 
-- **Detect visual changes** — screenshots are diffed against baselines by the `ui-scripts visual-diff` command; an interactive HTML report is published to GitHub Pages on every PR.
+- **Detect visual changes** — screenshots are diffed against baselines by the `ui-scripts visual-diff` command; an interactive HTML report is published to GitHub Pages on every PR. Each screenshot opens in a lightbox that switches between Baseline / Actual / Diff / Slider views and an **HTML** view that iframes the live rendered page (a static export of this app is published next to the report), so you can inspect the real DOM alongside the pixels.
 - **Detect a11y issues** — axe-core runs against every page.
 - **Detect unexpected console errors** — the spec's `afterEach` hook asserts `console.error` was not called.
 

regression-test/next.config.mjs

@@ -28,11 +28,20 @@ import webpack from 'webpack'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
+// When the built app is published to GitHub Pages alongside the visual-diff
+// report (so the report's "HTML" view can iframe the live page), its assets
+// live under a subpath like `/visual-regression/pr-123/app`. Setting basePath
+// makes Next emit and reference `/_next/...` under that prefix so the published
+// copy resolves. Left empty for local dev and the Cypress capture build, where
+// the app is served from the root of http://localhost:3000.
+const basePath = process.env.REGRESSION_APP_BASE_PATH || ''
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   // Fully static export: no SSR, no hydration mismatches that can cause
   // screenshot flakiness. `next build` writes a plain static site to `out/`.
   output: 'export',
+  ...(basePath ? { basePath } : {}),
   // Emits out/<route>/index.html so any static server (including http-server)
   // resolves /route without needing a .html fallback config.
   trailingSlash: true,