# Viewer Performance Optimization Report

## Baseline goals

- Desktop target: 60 FPS.
- Mobile target: 30 FPS minimum.
- No white flash during route/viewer load.
- No layout shift while assets stream.
- Interaction latency low enough for CAD-like orbit, pan, and zoom.

## Implemented optimizations

### Renderer profile

`ViewerCanvas` detects coarse/mobile pointers and low CPU core counts. It caps DPR to 1.5 on mobile and 2 on desktop, disables stencil, disables preserveDrawingBuffer, and avoids antialiasing on constrained mobile devices.

### Shadows

The viewer uses one high-quality directional shadow map and Drei contact shadows instead of many shadow-casting lights. This gives the machine a grounded premium look without a heavy multi-light shadow budget.

### Material preparation

`PreparedMachineRoot` clones materials once after model load. Runtime changes to opacity, clipping, wireframe, and highlight state then mutate instance-local materials and never corrupt Drei/GLTF caches.

### Exploded view transforms

Procedural assets group meshes by part. GLTF assets can tag group nodes as part roots. The exploded view only animates those root objects, not every triangle mesh.

### URL and FPS throttling

Camera snapshots are written to state at a throttled interval. FPS sampling updates twice per second. URL replacement is debounced by `useViewerUrlState()`.

### Reduced motion

When users request reduced motion, camera transitions and exploded transforms snap to the target state. This improves accessibility and avoids unnecessary animation work for those users.

## Asset recommendations

For production machine models:

- Use GLB rather than loose GLTF for fewer network requests.
- Use Draco for high-poly mechanical geometry.
- Use KTX2/Basis for environment-sensitive PBR textures.
- Merge only non-selectable fasteners and repeated minor details.
- Keep selectable parts as named nodes.
- Prefer instancing for repeated bolts, bearings, turbine blades, gear teeth, and compressor stators.
- Supply WebP thumbnails separately for catalogue cards.
- Avoid 4K textures unless the part is inspected at close range.

## Known budgets

Recommended first-pass budgets per machine:

| Asset type | Desktop budget | Mobile budget |
| --- | ---: | ---: |
| Triangles | 250k–600k | 80k–220k |
| Materials | < 80 | < 45 |
| Texture memory | < 180 MB | < 80 MB |
| Draw calls | < 250 | < 140 |
| Shadow casters | selectable major parts | major opaque parts only |

## Verification checklist

Before shipping a new machine asset:

1. Open on desktop and mobile viewport.
2. Confirm orbit remains smooth with labels on.
3. Toggle wireframe.
4. Enable exploded view at max separation.
5. Enable cross-section on X, Y, and Z.
6. Hide and fade every major part.
7. Select parts by clicking model and by component list.
8. Copy a share link and reload it in a new tab.
9. Confirm no console loader errors.
10. Inspect FPS status bar during interaction.