# Catalogue Implementation Blueprint

Mechanica’s foundation now has a typed implementation blueprint for the full 28-machine catalogue in `src/modules/machines/data/catalogueBlueprint.ts`. The runtime registry remains the public product metadata layer, but this blueprint is the deeper authoring contract: it records the component breakdown, animation channels, camera requirements, view modes, validation checks, and asset strategy each machine must satisfy before placeholder content is considered production-ready.

## Why this exists

The milestone already defines the architecture and registry schema. The remaining high-value gap was implementation depth for the promised catalogue: without a concrete machine-by-machine decomposition, later work can drift into inconsistent pivots, mismatched component names, one-off animations, or attractive but mechanically inaccurate GLB imports.

The blueprint is intentionally TypeScript rather than a prose-only table so future work can import it for:

- registry completeness audits,
- component-ID validation against GLB node names,
- animation channel QA,
- machine authoring checklists,
- catalogue progress reporting,
- build-time or Vitest validation.

The module validates itself on import for target count, duplicate IDs, duplicate component keys, duplicate animation keys, minimum component depth, minimum camera presets, and minimum validation checks.

## Catalogue coverage

| Category | Count | Coverage intent |
| --- | ---: | --- |
| Engines | 7 | Reciprocating, rotary, steam, and turbine examples. |
| Gearboxes | 6 | Parallel-shaft, epicyclic, differential, worm, cycloidal, and CVT power transmission. |
| Pumps | 5 | Centrifugal, positive-displacement, hydraulic, reciprocating, and peristaltic flow systems. |
| Mechanisms | 7 | Core kinematic references used by larger machines. |
| Structural systems | 3 | Load paths, hydraulic structures, and large-scale machinery context. |
| **Total** | **28** | Matches the funded catalogue target. |

## Implementation tiers

Tiers are not quality levels. They are build-order guidance for maximizing reuse and reducing technical risk.

### Tier 1 — Reference demonstrators

These should be implemented first because they prove the core viewer capabilities and provide reusable animation math.

- `inline-four-engine`
- `manual-synchromesh-transmission`
- `planetary-automatic-gearset`
- `open-differential`
- `centrifugal-pump`
- `slider-crank-mechanism`
- `geneva-drive`
- `cam-and-follower`

Tier 1 proves: cross-section, exploded view, component opacity, load-path overlays, flow overlays, exact crank kinematics, gear ratios, and intermittent motion.

### Tier 2 — Reusable variations

These reuse Tier 1 math while broadening the catalogue.

- `two-stroke-single-engine`
- `wankel-rotary-engine`
- `worm-reduction-gearbox`
- `belt-cvt`
- `external-gear-pump`
- `reciprocating-piston-pump`
- `peristaltic-pump`
- `scotch-yoke-mechanism`
- `four-bar-linkage`
- `rack-and-pinion-steering`
- `universal-joint`
- `hydraulic-excavator-arm`

Tier 2 proves: procedural curves, fluid packet visualization, exact linkage constraints, hydraulic cylinder solving, and viewer controls for motion variants.

### Tier 3 — Advanced assemblies

These require more complex model structure or multi-body constraints.

- `v6-engine`
- `steam-locomotive-cylinder`
- `cycloidal-reducer`
- `axial-piston-pump`
- `pratt-truss-bridge`

Tier 3 proves: banked transforms, valve timing overlays, eccentric reducers, swash-plate pump kinematics, and structural load-path displays.

### Tier 4 — High complexity / high visual payoff

These should wait until instancing, LOD, label scaling, and performance budgets are proven.

- `radial-aircraft-engine`
- `gas-turbine-core`
- `tower-crane-slewing-jib`

Tier 4 proves: high instance counts, large scene extents, blade/stage simplification, and complex structural overlays.

## Machine matrix

| ID | Primary engineering lesson | Required animation depth |
| --- | --- | --- |
| `inline-four-engine` | Four-stroke crank, piston, and valvetrain phasing. | Exact slider-crank piston motion, 2:1 cam timing, firing-order pulse overlay. |
| `v6-engine` | Bank angle packaging and shared crank behavior. | Bank-axis piston transforms, dual-bank cam timing, exhaust pulse routing. |
| `two-stroke-single-engine` | Port timing and crankcase scavenging. | One-revolution cycle, port exposure masks, transfer/exhaust flow arrows. |
| `radial-aircraft-engine` | Master rod and radial cylinder coordination. | Master/articulating rod kinematics, radial piston axes, pushrod events. |
| `wankel-rotary-engine` | Eccentric shaft and epitrochoid chamber volume. | Rotor orbit plus -1/3 rotor spin, chamber volume overlays. |
| `steam-locomotive-cylinder` | Double-acting piston and valve gear timing. | Wheel-to-crosshead kinematics, valve lap/lead/cutoff, steam flow routing. |
| `gas-turbine-core` | Brayton cycle through compressor, combustor, turbine. | Multi-spool rotation, pressure/temperature flow overlays. |
| `manual-synchromesh-transmission` | Constant-mesh gears and synchronizer engagement. | Gear-ratio rotations, sleeve translation, selected torque path. |
| `planetary-automatic-gearset` | Epicyclic speed relationships. | Sun/ring/carrier solver, planet spin/orbit, held-member mode changes. |
| `open-differential` | Carrier averaging and wheel speed difference. | Pinion/ring ratio, side gear average, spider spin from speed delta. |
| `worm-reduction-gearbox` | Right-angle high-ratio reduction. | Worm lead relation, wheel reduction, sliding contact highlight. |
| `cycloidal-reducer` | Eccentric orbit and pin engagement. | Disc orbit, counter-rotation, output pin averaging. |
| `belt-cvt` | Continuous ratio change. | Sheave translation, dynamic belt path, output speed from radius ratio. |
| `centrifugal-pump` | Impeller acceleration and volute recovery. | Impeller rotation, radial/tangential flow arrows, pressure gradient. |
| `external-gear-pump` | Positive displacement around gear outsides. | Counter-rotating gears, trapped volume packets, outlet pressure ripple. |
| `axial-piston-pump` | Swash plate displacement and valve timing. | Rotating barrel, swash-driven piston stroke, kidney-port flow state. |
| `reciprocating-piston-pump` | Check valves and pulsating discharge. | Slider-crank piston, pressure-driven check valves, discharge pulses. |
| `peristaltic-pump` | Roller occlusion through flexible tubing. | Roller orbit, tube deformation, fluid slug transport. |
| `slider-crank-mechanism` | Exact rotary-to-linear conversion. | Crank rotation, rod-angle solve, exact slider displacement. |
| `scotch-yoke-mechanism` | Pure sinusoidal reciprocation. | Crank rotation, yoke translation, slot contact marker. |
| `geneva-drive` | Intermittent indexing and dwell. | Continuous driver, stepped output, dwell lock highlight. |
| `cam-and-follower` | Rise-dwell-return lift profile. | Data-defined cam profile, follower lift, spring compression. |
| `four-bar-linkage` | Closed-chain kinematics and coupler curves. | Circle-intersection solve, rocker oscillation, coupler trail. |
| `rack-and-pinion-steering` | Steering rack translation and Ackermann geometry. | Pinion/rack mesh, tie-rod constraints, inner/outer wheel angles. |
| `universal-joint` | Misaligned shaft coupling and velocity variation. | Tangent-relation output angle, spider articulation, velocity overlay. |
| `pratt-truss-bridge` | Tension/compression load paths. | Moving panel load, member force colors, support reaction arrows. |
| `tower-crane-slewing-jib` | Slewing, trolley radius, and overturning moment. | Upper rotation, trolley travel, hoist cable, moment overlay. |
| `hydraulic-excavator-arm` | Hydraulic cylinders and pin-jointed force paths. | Cylinder length solves, boom/stick/bucket pivots, load-path overlay. |

## Authoring workflow

For each machine, production implementation should follow this sequence:

1. **Create or update runtime registry metadata**
   - Use the blueprint ID as the stable machine ID unless there is a deliberate migration.
   - Ensure category, title, summary, difficulty, facts, and thumbnail align with the blueprint.

2. **Model the component hierarchy**
   - Every blueprint component should map to one or more named scene nodes.
   - Node names should preserve component keys where possible, e.g. `inline-four-engine/pistons-rods/piston-01`.
   - Any component that is `sectionCritical` must remain readable in cross-section mode.

3. **Bind animation channels**
   - Implement the blueprint’s `animationChannels` as explicit driver channels.
   - Avoid hand-keyed loops when the blueprint specifies a physical relation.
   - Shared math should be extracted for slider-crank, gear-train, belt, hydraulic, and closed-chain linkage solvers.

4. **Implement viewer states**
   - Add the required camera presets.
   - Verify required viewer modes: exploded, section, ghosted, fluid-flow, load-path, or motion-trails.
   - Confirm component visibility and opacity controls work at the blueprint component level.

5. **Run validation**
   - Apply every `validationChecks` item as manual QA initially.
   - Promote repeatable checks into automated tests as solvers mature.
   - Compare GLB node names against component keys before asset merge.

## Recommended validation expansion

The current blueprint module validates structural completeness. The next valuable test layer is to add Vitest coverage around machine math utilities as they are implemented.

Suggested first automated tests:

- slider-crank displacement equals known top-dead-center and bottom-dead-center values,
- planetary solver satisfies `(Nr + Ns) * carrier = Nr * ring + Ns * sun`,
- differential carrier speed equals average axle speed,
- CVT belt ratio updates output speed continuously,
- universal joint output angle collapses to input angle when joint angle is zero,
- hydraulic cylinder solve preserves rod/barrel collinearity.

## Definition of done for a catalogue machine

A machine is production-ready only when all of the following are true:

- It has runtime registry metadata and a stable shareable route.
- It has a component hierarchy matching the blueprint.
- Each component can be selected, hidden, shown, and opacity-adjusted.
- Required camera presets are implemented and URL-addressable.
- Required viewer modes are implemented without breaking animation.
- Blueprint animation channels are physically plausible and not cosmetic-only.
- Engineering facts explain the visible motion.
- Asset complexity fits the performance budget.
- Keyboard and screen-reader labels expose the same component names as the visual UI.
- Blueprint validation checks pass in review.