# Core Machine Catalogue Expansion

This milestone expands the data-driven machine catalogue to cover all 28 Phase 1 core machines. The delivered registry includes educational metadata, procedural visualization descriptors, component hierarchies, guided-tour scripts, GLB replacement points, thumbnail strategy, and declarative animation modules.

## Files

- `src/modules/machines/types.ts` — shared strict TypeScript schema for machines, parts, camera presets, guided tours, thumbnails, asset replacement, materials, and animation definitions.
- `src/modules/machines/materials.ts` — reusable material tokens aligned with the Mechanica dark engineering visual system.
- `src/modules/machines/catalogue/*.ts` — category-specific Phase 1 machine definitions:
  - `engines.ts` — 8 engine and propulsion systems.
  - `gearboxesAndDrives.ts` — 6 gearbox and drive systems.
  - `pumpsAndFluid.ts` — 4 pump and hydraulic systems.
  - `mechanisms.ts` — 6 kinematic mechanisms.
  - `structuralOther.ts` — 4 bearing, brake, and turbocharger assemblies.
- `src/modules/machines/coreMachines.ts` — aggregate registry, lookup helpers, related-machine helpers, and registry validation.
- `src/animations/coreMachineAnimations.ts` — one standard declarative animation definition for each of the 28 Phase 1 machines.
- `src/modules/machines/index.ts` — public exports for catalogue consumers.

## Phase 1 Coverage

| # | Machine | Registry id | Category |
|---:|---|---|---|
| 1 | Four Stroke Petrol Engine | `four-stroke-petrol-engine` | Engines |
| 2 | Two Stroke Engine | `two-stroke-engine` | Engines |
| 3 | Diesel Engine | `diesel-engine` | Engines |
| 4 | V8 Engine | `v8-engine` | Engines |
| 5 | Wankel Rotary Engine | `wankel-rotary-engine` | Engines |
| 6 | Steam Engine | `steam-engine` | Engines |
| 7 | Jet Engine (Turbojet) | `turbojet-engine` | Engines |
| 8 | Turbofan Engine | `turbofan-engine` | Engines |
| 9 | Planetary Gearbox | `planetary-gearbox` | Gearboxes & Drives |
| 10 | Differential Gear | `differential-gear` | Gearboxes & Drives |
| 11 | Manual Gearbox (5-speed) | `manual-gearbox-5-speed` | Gearboxes & Drives |
| 12 | CVT | `cvt-transmission` | Gearboxes & Drives |
| 13 | Worm Gear Drive | `worm-gear-drive` | Gearboxes & Drives |
| 14 | Bevel Gear Set | `bevel-gear-set` | Gearboxes & Drives |
| 15 | Centrifugal Pump | `centrifugal-pump` | Pumps & Fluid Systems |
| 16 | Gear Pump | `gear-pump` | Pumps & Fluid Systems |
| 17 | Piston Pump | `piston-pump` | Pumps & Fluid Systems |
| 18 | Hydraulic Cylinder | `hydraulic-cylinder` | Pumps & Fluid Systems |
| 19 | Scotch Yoke | `scotch-yoke` | Mechanisms |
| 20 | Geneva Drive | `geneva-drive` | Mechanisms |
| 21 | Cam and Follower | `cam-and-follower` | Mechanisms |
| 22 | Rack and Pinion | `rack-and-pinion` | Mechanisms |
| 23 | Slider Crank | `slider-crank` | Mechanisms |
| 24 | Toggle Clamp | `toggle-clamp` | Mechanisms |
| 25 | Ball Bearing | `ball-bearing` | Structural / Other |
| 26 | Roller Bearing | `roller-bearing` | Structural / Other |
| 27 | Disc Brake Caliper | `disc-brake-caliper` | Structural / Other |
| 28 | Turbocharger | `turbocharger` | Structural / Other |

## Registry Format

Each `MachineDefinition` contains:

- Stable `id` and `slug` values for routing, sharing, favourites, and asset paths.
- Catalogue metadata: title, category, difficulty, complexity score, summary, searchable keywords, related machines, and thumbnail strategy.
- Educational layer: one-paragraph description, engineering facts, part descriptions, engineering notes, and guided-tour steps.
- 3D layer: procedural part primitive, transform, material token, label anchor, cross-section behavior, exploded-view vector, default visibility, and opacity.
- Camera layer: standard front, back, left, right, top, and isometric presets.
- Asset layer: GLB replacement information including path, root node name, and required part node ids.
- Animation hook: `animationModuleId`, matching the id exported by `src/animations/coreMachineAnimations.ts`.

## Adding a New Machine

1. Choose the appropriate category file under `src/modules/machines/catalogue/`.
2. Create a `const parts = [...]` array using `makePart`.
3. Add a `makeMachine({ ... })` entry with:
   - unique `id` and `slug`,
   - category and difficulty,
   - at least four facts,
   - related machine ids,
   - a thumbnail strategy via `thumbnail(...)`,
   - hierarchy groups,
   - camera presets via `standardCameraPresets(radius)`,
   - guided tour steps via `tourStep(...)`,
   - `animationModuleId`.
4. Add a matching `animation(...)` entry in `src/animations/coreMachineAnimations.ts`.
5. Confirm:
   - `validateCoreMachineRegistry().ok === true`
   - `validateCoreMachineAnimations().ok === true`

The registry is intentionally procedural-first. A new machine can ship educationally useful geometry without waiting on CAD assets.

## GLB Replacement Points

Every machine automatically receives an asset replacement descriptor:

```ts
{
  glbPath: `/assets/machines/${slug}/${slug}.glb`,
  previewImagePath: `/assets/machines/${slug}/preview.webp`,
  rootNodeName: slug,
  partNodeMap: {
    [partId]: partId
  }
}
```

To replace a procedural assembly with a professional GLB:

1. Export a GLB to the configured `glbPath`.
2. Name the root group exactly as `rootNodeName`.
3. Name each top-level part group or mesh with the registry `part.id`.
4. Keep optional meshes such as annotations, cutaway shells, fluid paths, and measurement rigs under separate groups if desired.
5. The viewer can then bind selection, opacity, visibility, exploded view, labels, and tour highlighting to the same part ids without core code changes.

If a GLB omits a part node, the procedural fallback for that part can remain active. This supports progressive asset replacement.

## Procedural Visualization Strategy

The procedural descriptions are diagrammatic rather than CAD-exact. The goal is to communicate mechanism function while keeping the catalogue lightweight and immediately browsable.

Primitive kinds include:

- generic shapes: `box`, `cylinder`, `sphere`, `torus`,
- mechanical primitives: `gear`, `bevel-gear`, `worm`, `rack`, `pulley`, `belt`, `spring`, `cam`, `rotor`,
- system primitives: `housing`, `pipe`, `flow-path`, `valve`, `seal`, `caliper`, `pad`,
- learning overlays: `annotation-plane`, `custom`.

Each primitive carries parameters and modelling hints so a renderer can choose the best available implementation. A high-end renderer can interpret the same data as instanced meshes, while a basic renderer can fall back to bounding solids.

## Animation Modules

`src/animations/coreMachineAnimations.ts` exports:

- `CORE_MACHINE_ANIMATIONS`
- `CORE_MACHINE_ANIMATION_BY_MACHINE_ID`
- `getCoreMachineAnimation(machineId)`
- `validateCoreMachineAnimations()`

Each machine has a `MachineAnimationDefinition` with:

- default RPM and RPM range,
- loop mode (`continuous`, `reciprocating`, or `stepped-indexed`),
- cycle steps for playhead stepping and guided learning,
- declarative tracks such as rotation, linear oscillation, angular oscillation, orbit, flow, scale pulse, material pulse, visibility windows, ratio morph, and indexed step.

The core animation player should not contain machine-specific logic. It should read tracks and apply transforms or semantic overlays by part id.

## Thumbnail Strategy

All Phase 1 machines default to `procedural-snapshot` thumbnails. Catalogue cards can render the procedural assembly from the specified camera preset and highlight `heroPartIds` plus `accentPartId`.

When art-directed thumbnails become available:

1. Save a static image under `/assets/machines/{slug}/preview.webp`.
2. Change the `ThumbnailStrategy.kind` to `static-image`.
3. Keep hero part ids intact for search highlighting, fallback snapshot generation, and accessibility descriptions.

## Validation

The registry provides two validation helpers:

```ts
import { validateCoreMachineRegistry } from '@/modules/machines';
import { validateCoreMachineAnimations } from '@/animations/coreMachineAnimations';

const registryResult = validateCoreMachineRegistry();
const animationResult = validateCoreMachineAnimations();
```

They check duplicate ids, missing parts, missing cameras, guided-tour references, GLB replacement part ids, animation-module id consistency, and animation track part references.

## Performance Notes

- Procedural part definitions are grouped by machine and category for lazy imports or bundle splitting.
- Repeated entities such as balls, rollers, gear teeth, and turbine blades are represented with count/array parameters so the renderer can use instancing.
- Complex engines use grouped semantic parts where appropriate; professional GLBs may expose finer child meshes inside stable top-level part ids.
- Flow paths and learning overlays are separate selectable parts, allowing users to hide them on lower-end devices.
- The asset strategy allows compressed GLB, Draco, and KTX2 additions without schema changes; the loader can infer companion compressed assets from the configured GLB path.

## Accessibility Notes

- Every part has a name and description suitable for tooltips, detail drawers, and screen-reader summaries.
- Guided-tour steps include captions and focus part ids.
- Thumbnail strategies include descriptive alt text.
- Stable part ids allow keyboard-driven component list selection independent of WebGL pointer picking.