Preview Environments Are Evidence Machines

1 day ago

A preview environment should not be just a place a human clicks around.

It should be an evidence machine.

The useful output of a preview is not only a URL. It is a structured record of what was built, what routes were reachable, what the browser observed, what changed at runtime, and what claims that evidence is strong enough to support.

The link is for inspection.

The evidence is for admission.

PATCH

BUILD

PREVIEW

ROUTES

BROWSER

A11Y

BUNDLE

PROOF

A preview turns a patch into route, browser, accessibility, bundle, and runtime proof surfaces.

The Preview Has A Job

Preview environments often sit outside the review system.

A bot comments with a link. A human opens it. Maybe someone notices a broken page. Maybe nobody does. The preview existed, but most of what it learned never became durable.

For agent work, that is too weak.

If a candidate changes a UI route, the preview should produce evidence:

which commit was deployed
which environment variables were present
which routes were probed
which browser and viewport ran
which DOM and accessibility snapshots were captured
which user interactions were replayed
which bundle and API contracts changed
which claims are still out of scope

The preview is a runtime oracle. It should speak in records, not vibes.

Runtime Proof Is Bounded

The preview cannot prove the whole product works.

It can prove bounded claims.

That boundary is what makes it useful. A route probe can prove that /settings/billing loads for a test account under one feature flag set. A focus probe can prove that a modal traps focus after one interaction. A layout probe can prove that a component did not shift outside a threshold at three viewports.

Those are small claims, but they are real claims.

Surface	Probe	Measured signal	Admission route
Selector reachabilityclass rename, CSS Module export, selector edit	Target probeResolve selectors against the output DOM.	Matched elements, orphaned selectors, intended target moves	Admit targetThe selector still reaches the same semantic target.
Viewport layoutmedia rule, container query, spacing, position	Viewport matrixRender declared widths and compare geometry.	Bounding boxes, overlap, visibility, scroll range	Gate layoutThe layout holds for the declared viewport set.
Interaction statehover, focus, disabled state, input workflow	Interaction traceReplay the smallest user path through the output.	Focus order, enabled controls, event result, state transition	Gate workflowThe workflow remains reachable after the merge.
Accessibility treerole, label, aria relationship, hidden content	A11y snapshotRead the browser accessibility tree.	Accessible name, role, state, relationships, tab stop	Require proofThe control keeps its user-facing semantics.
Hydration boundaryserver markup, client state, framework runtime	Hydration probeLoad server output and observe client takeover.	Console errors, markup drift, event attachment, first state	Block driftThe rendered output survives client hydration.

Preview proof should identify the probe, the observed signal, and the claim boundary it can actually support.

The Evidence Bundle

A preview evidence bundle should be boringly inspectable.

Checkout Flow Preview

Build: commit 8f31, app bundle hash, server image hashThe runtime proof is bound to the exact deployed output.
Route probes: /cart, /checkout, /checkout/successThe route surface is declared instead of discovered casually.
Browser signals: DOM snapshot, console errors, network failures, hydration statusThe browser returns machine-readable observations.
Accessibility: landmarks, labels, focus order, critical axe resultsThe proof names interaction and accessibility boundaries.
Non-claims: payment provider sandbox, logged-out checkout, mobile SafariThe evidence says what it did not cover.

A preview receipt makes a deployed environment reviewable after the tab is closed.

This is not the same as screenshot testing.

Screenshots can help, but the proof needs source binding and structured observations. A screenshot can show what the page looked like. It cannot by itself say which route, commit, selector, focus state, accessibility tree, or network trace produced the image.

Preview Diffs Matter

The most useful preview compares old and new runtime surfaces.

SurfaceClaimRequired proofCurrent evidenceRoute

RequiredRouteTouched routes still loadRoute probe with status and shell assertionsHTTP status, app boot, route markerAdmit route

RequiredDOMExpected structure is presentDOM snapshot and locator assertionsStable selectors, text, landmarksAdmit structure

MissingLayoutCritical layout did not move unexpectedlyViewport measurementsBounding boxes and movement thresholdsReview drift

RequiredAccessibilityInteraction remains operableA11y tree and focus probeLabels, roles, focus orderGate

MissingBundleRuntime cost changed within policyBundle delta and module diffEntrypoint size, new deps, split chunksReview cost

Preview admission is stronger when the environment returns comparable evidence objects.

Preview Environments Should Feed The Queue

A failed preview should not end as a red badge.

It should create work.

route probe failed -> rerun with server logs
hydration mismatch -> create focused component task
layout drift -> request viewport-specific proof
accessibility regression -> block admission and open fix task
bundle growth -> route to dependency review

That makes previews part of the coordination loop. They are not a destination for human attention. They are a source of structured proof, routes, and sharper follow-up tasks.

The Mental Model

A preview is a deployed candidate plus probes.

The URL is useful because humans can inspect it.

The evidence is useful because the system can admit, rerun, split, or block from it.

SHAPE

SHIFT