# Clean Checkout Validation

This document defines the final validation procedure for the production-hardened Mechanica application. It is intended for maintainers or CI runners that can execute commands on a clean machine; the source deliverable intentionally does not include a hand-authored lockfile.

## Required environment

Use a clean clone of the repository and a current Node runtime:

- Node.js 20 LTS or newer is recommended.
- npm must be available on `PATH`.
- Playwright browser dependencies must be installable on the runner for end-to-end tests.
- The runner should have enough memory for Vite/Three.js bundling; 4 GB is a practical minimum, 8 GB is preferred.

Confirm the runtime:

```bash
node --version
npm --version
```

## One-command validation harness

The repository includes a Node-only validation harness that runs the funded release gates in order and writes a JSON report:

```bash
node scripts/validate-clean-checkout.mjs --install-playwright --json artifacts/validation-report.json
```

The harness performs:

1. Essential file and package-manager sanity checks.
2. `npm install --no-audit --fund=false`.
3. Optional format check if a matching npm script exists.
4. ESLint via the `lint` npm script.
5. TypeScript validation via `typecheck`, or `npx tsc -p tsconfig.json --noEmit` when no script is present.
6. Vitest unit tests via the configured script or `npx vitest run`.
7. Production build via `npm run build`.
8. Dist asset metric collection and performance-budget review.
9. Playwright browser install when `--install-playwright` is provided.
10. Playwright end-to-end tests via the configured script or `npx playwright test`.

The command exits non-zero if any required gate fails.

## Manual validation commands

If debugging step-by-step, run the same gates manually from the repository root:

```bash
npm install --no-audit --fund=false
npm run lint
npm run typecheck
npm run test:unit -- --run
npm run build
npx playwright install --with-deps
npm run test:e2e
```

If the actual `package.json` uses different script names, inspect `package.json` and run the equivalent scripts. Do not skip type checking, unit tests, production build, or Playwright unless documenting a temporary infrastructure outage.

## Validation variants

### Fast local loop

Use this after dependencies are already installed and before opening a pull request:

```bash
node scripts/validate-clean-checkout.mjs --skip-install --skip-e2e
```

### Full CI evidence with all failures collected

Use this when preparing a failure report because it continues after failures and captures as much evidence as possible:

```bash
node scripts/validate-clean-checkout.mjs \
  --continue-on-error \
  --install-playwright \
  --json artifacts/validation-report.json
```

### Enforced bundle review

The default dist budget check reports warnings without failing. To make budget regressions a hard gate:

```bash
node scripts/validate-clean-checkout.mjs \
  --install-playwright \
  --enforce-budgets \
  --json artifacts/validation-report.json
```

Default review budgets are intentionally conservative for a Three.js/R3F application:

- Total JavaScript gzip estimate: 900 KB
- Largest JavaScript chunk gzip estimate: 450 KB
- Total CSS gzip estimate: 120 KB
- Largest single asset: 2 MB

Adjust these only with a documented reason, such as introducing a compressed GLB/KTX2 production asset.

## Manual browser QA after automated tests

After the automated run passes, perform a short manual browser check:

1. Start the production preview:
   ```bash
   npm run build
   npm run preview
   ```
2. Open the local preview URL in Chromium and Firefox.
3. Verify the catalogue renders without white flashes or layout shifts.
4. Open at least one machine viewer route.
5. Confirm orbit controls, part selection, playback, explode slider, wireframe, annotations, and camera presets work.
6. Copy a share link, open it in a new tab, and confirm the machine/view state is restored.
7. Toggle reduced-motion preferences in the app and, if possible, the OS/browser setting.
8. Resize through desktop, tablet, and mobile widths.
9. Navigate top-level controls with keyboard only.
10. Confirm the WebGL fallback appears when WebGL is unavailable or blocked.

## Evidence to retain

For final signoff, retain:

- Terminal output from the full harness command.
- `artifacts/validation-report.json`.
- Playwright HTML report or trace output when tests fail.
- A screenshot of the catalogue and a screenshot of a machine viewer on a mobile viewport.
- The deployed Vercel preview URL.
- Any environment variables used, excluding secrets.

## Acceptance criteria

The milestone is ready to mark complete only when all of the following are true on an actual runner:

- Dependency installation succeeds from a clean checkout.
- ESLint exits with code 0.
- TypeScript exits with code 0 under strict mode.
- Vitest exits with code 0.
- Vite production build exits with code 0 and emits `dist/`.
- Playwright exits with code 0 in CI or an equivalent clean local environment.
- Any discovered runtime, selector, accessibility, mobile, sharing, or browser-regression failures are fixed in source code and revalidated.