# Mechanica — Mechanical Systems Explorer

Mechanica is a Vite + React + TypeScript application for exploring mechanical systems through interactive 3D visualizations. It combines a searchable engineering catalogue, a production-grade Three.js viewer, procedural animation modules, guided learning tours, shareable view states, and responsive CAD-inspired interface panels.

This README is the maintainer entry point for the final production hardening milestone. Deeper operational documents live in [`docs/`](./docs).

## Production feature set

- Catalogue of 28 phase-one machines across engines, gearboxes and drives, pumps and fluid systems, mechanisms, and structural systems.
- Interactive 3D viewer with orbit controls, camera presets, exploded view, wireframe/cross-section modes, annotations, hover and selected-part states.
- Animation player abstraction with play/pause/restart, RPM/time-scale control, step-through mode, and machine-specific physically believable loops.
- Guided tours with camera movement, highlighted parts, and explanatory captions.
- Local favourites and persistent viewer settings.
- URL-encoded machine/view state for sharing.
- Dark premium engineering UI using Tailwind, CSS variables, glass panels, skeleton loading, and responsive layouts.
- Production hardening assets: strict TypeScript, linting, formatting, tests, Vercel config, CSP/security headers, bundle splitting, and documentation.

## Requirements

- Node.js `>=20`
- npm `>=9`
- A browser with WebGL 2 support for full viewer functionality

No lockfile is hand-written in this repository. Generate one on a clean machine with the first `npm install`, then commit the generated lockfile from that real install if the team wants deterministic CI.

## Quickstart

```bash
cp .env.example .env.local
npm install
npm run dev
```

Open <http://localhost:5173>.

## Production build

```bash
npm run qa
npm run preview
```

`npm run qa` runs type-checking, ESLint, coverage-enabled unit tests, and a production build. `npm run preview` serves the built app from `dist/` using Vite’s preview server.

## Scripts

| Command | Purpose |
| --- | --- |
| `npm run dev` | Start Vite development server. |
| `npm run build` | Run TypeScript project build and Vite production build. |
| `npm run preview` | Serve `dist/` on all interfaces. |
| `npm run preview:local` | Serve `dist/` on localhost only. |
| `npm run typecheck` | Validate TypeScript without emitting files. |
| `npm run lint` | Run ESLint across the repository. |
| `npm run lint:fix` | Apply safe ESLint fixes. |
| `npm run format` | Format with Prettier. |
| `npm run format:check` | Check formatting in CI. |
| `npm run test` | Run Vitest unit/component tests. |
| `npm run test:watch` | Run Vitest in watch mode. |
| `npm run test:coverage` | Generate coverage reports in `coverage/`. |
| `npm run test:e2e` | Run Playwright regression tests. |
| `npm run test:e2e:headed` | Run Playwright with visible browsers. |
| `npm run analyze` | Build with bundle visualizer output at `dist/bundle-report.html`. |
| `npm run qa` | Local pre-merge quality gate. |

## Environment variables

Mechanica only exposes public, non-secret client variables through the `VITE_` prefix.

| Variable | Default/example | Description |
| --- | --- | --- |
| `VITE_APP_NAME` | `Mechanica` | Display name used by metadata and shell UI. |
| `VITE_APP_ORIGIN` | `http://localhost:5173` | Canonical origin used when generating share URLs. |
| `VITE_DEFAULT_MACHINE` | `four-stroke-petrol-engine` | Machine opened by default viewer routes. |
| `VITE_ASSET_BASE_URL` | `/assets/machines/` | Base path for GLB/GLTF machine assets. |
| `VITE_DRACO_DECODER_PATH` | `/draco/` | Public path for Draco decoder files. |
| `VITE_KTX2_TRANSCODER_PATH` | `/basis/` | Public path for Basis/KTX2 transcoder files. |
| `VITE_ENABLE_PERF_OVERLAY` | `false` | Enables developer performance overlay when implemented in runtime shell. |
| `VITE_ENABLE_DEBUG_CAMERA` | `false` | Enables debug camera telemetry controls. |
| `VITE_ENABLE_SOURCE_MAPS` | `false` | Emits production sourcemaps when set to `true`. |
| `VITE_SOCIAL_IMAGE` | `/social/mechanica-og.svg` | Default share preview image. |
| `VITE_SUPPORT_EMAIL` | `maintainers@mechanica.local` | Non-secret maintainer contact for support messaging. |

Playwright also reads `PLAYWRIGHT_BASE_URL` and `PLAYWRIGHT_SKIP_WEBSERVER`.

## Deployment

Mechanica is Vercel-ready via [`vercel.json`](./vercel.json).

Recommended Vercel settings:

- Framework preset: **Vite**
- Install command: `npm install`
- Build command: `npm run build`
- Output directory: `dist`
- Node.js: latest Vercel Node 20 runtime or newer
- Environment variables: copy the public keys from `.env.example` and adjust `VITE_APP_ORIGIN`

See [`docs/DEPLOYMENT.md`](./docs/DEPLOYMENT.md) for preview deployments, production promotion, cache policy, rollback, and social preview strategy.

## Documentation index

- [`docs/DEPLOYMENT.md`](./docs/DEPLOYMENT.md) — Vercel deployment, headers, caching, environment configuration, rollback.
- [`docs/STATE_MANAGEMENT.md`](./docs/STATE_MANAGEMENT.md) — Zustand state slices, persistence, URL sync, migrations, selector policy.
- [`docs/MACHINE_AUTHORING_GUIDE.md`](./docs/MACHINE_AUTHORING_GUIDE.md) — registry format and process for adding machines.
- [`docs/ASSET_PIPELINE_AND_LOADING.md`](./docs/ASSET_PIPELINE_AND_LOADING.md) — GLB/GLTF, Draco, KTX2, decoder files, asset budgets.
- [`docs/PERFORMANCE_OPTIMIZATION_REPORT.md`](./docs/PERFORMANCE_OPTIMIZATION_REPORT.md) — budgets, implemented optimizations, profiling workflow.
- [`docs/PRODUCTION_HARDENING.md`](./docs/PRODUCTION_HARDENING.md) — error boundaries, lazy loading, reduced motion, keyboard, mobile tuning.
- [`docs/SOCIAL_META_AND_SHARING.md`](./docs/SOCIAL_META_AND_SHARING.md) — share URL schema and meta tag strategy.
- [`docs/QA_CHECKLIST.md`](./docs/QA_CHECKLIST.md) — release checklist for maintainers.
- [`docs/REGRESSION_TEST_PLAN.md`](./docs/REGRESSION_TEST_PLAN.md) — automated and manual regression coverage plan.

## Maintainer quality bar

Before merging production changes:

1. `npm install` on a clean checkout.
2. `npm run qa`.
3. `npm run test:e2e`.
4. Open the production preview on desktop, tablet, and mobile widths.
5. Validate at least one machine from each category.
6. Copy a share link, open it in a clean browser profile, and confirm the same machine/view state loads.
7. Test with `prefers-reduced-motion: reduce`.
8. Run `npm run analyze` and inspect `dist/bundle-report.html` for accidental large chunks.

## Third-party API targets

The production configuration targets Vite 5, React 18, Three.js `0.166.x`, React Three Fiber 8, Drei 9, GSAP 3, Framer Motion 11, Zustand 4, Vitest 1, and Playwright 1.45. Three.js loader APIs, Drei helper APIs, and Vercel routing/header semantics should be checked against the resolved package versions during the first real install because those ecosystems can change between minor releases.