Visual View Diff

Visual View Diff Skill

Renders the extension's webview panels headlessly, screenshots them, and reports which views changed compared to a baseline commit.

The screenshots are the deliverable. Posting them anywhere — a PR comment, a job summary, an artifact upload — is deliberately not part of this skill. It answers exactly one question: what changed visually, and what does it look like? Whoever wants to publish that answer reads report.md and the PNGs.

The publisher for pull requests is the ui-checks job in .github/workflows/ci.yml: it runs this diff against the PR's merge base and posts the before/after/diff images as one comment on the PR (replaced on every push) through gh pr comment --attach, rendered by .github/workflows/scripts/visual-diff-comment.js. An agent opening a UI PR does not have to attach screenshots by hand — it has to make sure the change is visible to this harness (see "States" below) and say in the PR body which views it expects to change.

When to use it

• A change touches vscode-extension/src/webview/**, the shared webview CSS, or a get*Html method in extension.ts.
• A refactor is supposed to be visually neutral and you want proof.
• You want before/after images of a UI change for a human to look at.

Why this exists (and why it does not open VS Code)

The repo forbids agents from launching a real editor window — see "Never Launch a Real Editor/IDE Instance" in .github/copilot-instructions.md. That rules out the Extension Development Host, and with it the existing aiEngineeringFluency.runLocalViewRegression command, which only a human can run and which checks DOM metrics (node counts, text length) rather than appearance.

This skill covers the gap: it renders the real webview bundles outside VS Code. Every panel's HTML shell in extension.ts is the same four ingredients — a <div id="root">, a window.__INITIAL_<VIEW>__ payload, the shared JSON config globals, and <script src="dist/webview/<view>.js">. The harness reproduces that shell around a committed fixture and supplies the --vscode-* theme tokens VS Code would normally inject, then lets the real bundle render.

Nothing about the views is re-implemented, which is what makes the screenshots trustworthy: if rendering code changes, the screenshot changes with it.

Usage

Everything runs from the repo root. Bundles must be built first (cd vscode-extension && npm install && node esbuild.js).

Compare against the baseline commit (the usual case)

node .github/skills/visual-view-diff/visual-diff.js
# or, from vscode-extension/:  npm run visual:diff

This builds the webviews at the merge base with origin/main in a temporary git worktree, builds the working tree, renders both, and compares. Your checkout is never touched — no stashing, no branch switching.

# Compare against something else, or render both themes
node .github/skills/visual-view-diff/visual-diff.js --base origin/main --theme both
node .github/skills/visual-view-diff/visual-diff.js --view details,chart

Output lands in visual-output/ (git-ignored):

visual-output/
├── baseline/   <view>.<theme>.png     — before
├── current/    <view>.<theme>.png     — after
└── diff/       <view>.<theme>.diff.png, report.md, report.json

A view rendered in one of its declared states (a tab, a mode) is named <view>--<state>.<theme>.png, e.g. usage--tools.dark.png.

Just screenshot the current state

node .github/skills/visual-view-diff/render-views.js --out visual-output/current --theme both
# or, from vscode-extension/:  npm run visual:render -- --theme both

Compare two directories you already have

node .github/skills/visual-view-diff/diff-screenshots.js \
  --baseline visual-output/baseline --current visual-output/current --out visual-output/diff

Reading the result

diff/report.md is a Markdown summary — a table of every view with its status (changed / unchanged / added / removed), how many pixels moved, and the image size. report.json is the same data for scripting.

Diff images paint changed pixels magenta over a dimmed copy of the new screenshot, so a change is easy to locate in context.

A changed view is not automatically a problem. Read the diff image and decide: intended restyle, or accidental regression? The tool reports; you judge.

Requirements

• Playwright with Chromium. Intentionally not a dependency of the extension — this is developer/CI tooling, not shipped code. lib/browser.js finds a local or global install, or the pinned one CI uses under .github/workflows/dependencies/playwright; if none exists: npm install -g playwright && npx playwright install chromium. The Copilot coding agent gets that pinned install from copilot-setup-steps.yml, and Claude Code's cloud environment ships a global Playwright, so in both an agent can run this skill as-is.
• Built webview bundles in vscode-extension/dist/webview/.
• vscode-extension/node_modules — the baseline worktree symlinks it rather than running a second npm install.

Fixtures

Each view renders from a committed JSON fixture in fixtures/, holding exactly the payload extension.ts passes to that view. Fixtures use fixed timestamps and synthetic numbers so two runs of the same code produce byte-identical screenshots — a Date.now() anywhere would make every view diff against itself.

A fixture can reference a repo data file instead of copying it:

{ "categories": { "$fromRepoJson": "src/fluencyLevelData.json" } }

That keeps the fixture small and means editing the source file shows up as the visual change it really is.

Adding a view

1. Find the view's HTML shell in extension.ts (get<Name>Html) and note the window.__INITIAL_*__ global it assigns.
2. Add an entry to views.config.json — id, bundle (its esbuild entry point name in esbuild.js), global, and fixture.
3. Write fixtures/<id>.json with that payload.
4. Check it renders: node render-views.js --view <id> --out /tmp/check.

A view whose #root comes out empty is reported as an error, not silently screenshotted blank — a fixture missing a required field would otherwise pass as "no visual change" forever.

dashboard is enabled with synthetic Azure rollups and an additional __DASHBOARD_CONFIG__ global declared in the registry's globals field. Both backend tabs render without contacting a live backend. The in-editor regression runner still skips it because that runner needs a configured live backend. When enabling a previously disabled view, the visual baseline uses the new fixture on both bundles to compare layouts rather than a loading screen against data.