# Mechanica — Mechanical Systems Explorer

Mechanica is a premium mechanical engineering reference shell built with React, TypeScript, Vite, Tailwind CSS, Zustand, and Framer Motion. This milestone delivers the production catalogue and application chrome: a registry-driven machine library, responsive filters, bookmark persistence, light/dark/system theming, skeleton loading states, route metadata, and accessibility-first shared UI primitives.

## What is included in this milestone

- Dark engineering visual system with CSS variables and Tailwind tokens.
- Responsive application shell with top navigation, skip link, status bar, and route layout.
- Searchable, filterable, sortable catalogue for **all 28 core machines** and **8 stretch machines**.
- LocalStorage-backed favourites/bookmarks via Zustand persistence.
- Difficulty, category, phase, complexity, part-count, and engineering fact metadata.
- Machine detail/reference route generated from the same registry as the catalogue.
- Skeleton card loading states with stable dimensions.
- Focus-visible styling, semantic buttons, ARIA labels, native form controls, and reduced-motion handling.
- Vercel-ready SPA deployment configuration.

The 3D viewer implementation is intentionally not mounted in this milestone; the package still declares the planned Three.js/R3F/Drei/GSAP dependencies so later viewer milestones can build on the same repository without manifest churn.

## Requirements

- Node.js `>=18.18`
- npm, pnpm, or yarn. Examples below use npm.

## Setup

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

Open `http://localhost:5173`.

## Build and validation

```bash
npm run lint
npm run build
npm run preview
```

No lockfile is committed. Generate one on the target machine with `npm install` so package resolution reflects the current registry state.

## Environment variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `VITE_APP_NAME` | `Mechanica` | Application name used in UI and metadata. |
| `VITE_APP_TAGLINE` | `Mechanical Systems Explorer` | Short product tagline. |
| `VITE_PUBLIC_BASE_URL` | `http://localhost:5173` | Base URL used for canonical links and social metadata. |

## Routes

| Route | Description |
| --- | --- |
| `/` | Catalogue homepage with URL-synced search/filter/sort state. |
| `/machines/:machineSlug` | Registry-driven machine reference page. |
| `*` | Accessible 404 route with catalogue recovery action. |

## Catalogue URL parameters

The catalogue page reads and writes these parameters:

- `q`: search query
- `category`: comma-separated category labels
- `difficulty`: comma-separated difficulty labels
- `phase`: comma-separated `core` / `stretch`
- `sort`: `name`, `newest`, or `complexity`
- `favourites`: `true` when enabled
- `view`: `comfortable` or `compact`

Example:

```text
/?q=gear&category=Gearboxes+%26+Drives&difficulty=Intermediate&sort=complexity
```

## Documentation

- [`docs/ui-shell.md`](docs/ui-shell.md): visual system, layout, shared components, responsive behaviour, and accessibility.
- [`docs/catalogue-registry.md`](docs/catalogue-registry.md): machine registry schema and how to add new machines.
- [`docs/state-management.md`](docs/state-management.md): Zustand stores, persistence, URL synchronisation, and theme state.

## Deployment on Vercel

1. Import the repository in Vercel.
2. Set `VITE_PUBLIC_BASE_URL` to the production origin.
3. Use the default Vite settings or the included `vercel.json`:
   - Build command: `npm run build`
   - Output directory: `dist`
4. Deploy.

The SPA rewrite in `vercel.json` ensures direct visits to `/machines/:machineSlug` resolve to `index.html`.

## Target dependency families

This code targets React 18, React Router 6, Zustand 5, Framer Motion 11, Vite 5, Tailwind CSS 3.4, Three.js 0.170, React Three Fiber 8, and Drei 9. Because this environment cannot run an install or compiler, maintainers should verify the resolved minor versions with `npm run check` after generating a lockfile.
