# Item Preview Viewer Guide

The item framework stays renderer-neutral while exposing a complete 3D preview
state for inventory, vendor, loot, and equipment inspection UI.

## Preview State

`createItemPreviewViewer(database, item)` accepts either an item definition or
an item instance. It resolves the item definition, applies localization when
requested, and returns:

- preview asset references for icon, mesh, and material
- a scene node with transform data for the item mesh
- orbit camera settings with distance and pitch limits
- studio lighting settings
- orbit, zoom, turntable, and hotspot inspection controls
- hotspots derived from stats, enchantments, and durability
- an accessibility label for screen-reader narration
- a snapshot containing camera, selected hotspot, and asset refs

Items without meshes return `status: "icon_only"` so UI can fall back to a flat
icon preview without losing the inspection panel.

## Controls

Use immutable helpers to update state:

- `rotateItemPreview` adjusts orbit yaw and pitch.
- `zoomItemPreview` clamps camera distance to configured bounds.
- `setItemPreviewTurntable` enables or disables automatic rotation.
- `selectItemPreviewHotspot` selects a stat, enchantment, or durability marker.
- `createItemPreviewSnapshot` captures the current view for thumbnails or tests.

Renderer implementations should treat the returned state as the source of truth
and can map the scene node and camera data to Three.js, WebGPU, native engine,
or editor viewport primitives.
