# scena v1.4.0 Release Notes

Status: ready after local gates and browser visual proof.

## Install

```toml
[dependencies]
scena = "1.4"
```

## Easy-Use Named Primitives

This release closes the gap between "Rust renderer that works" and "library
beginners can pick up without writing magic constants." Every place v1.3.0
forced a user to write raw coordinates, magic floats, or hand-rolled rigs,
v1.4.0 ships a named primitive.

- `Color` named constants (`TRANSPARENT`, `BLACK`, `WHITE`, `GRAY`,
  `LIGHT_GRAY`, `DARK_GRAY`, `CHARCOAL`, `STUDIO_BACKDROP`, `WARM_WHITE`,
  `COOL_WHITE`, `RED`, `GREEN`, `BLUE`, `ORANGE`, `YELLOW`, `CYAN`,
  `MAGENTA`) plus `Color::from_hex` and `Color::from_kelvin` for the
  designer-friendly and lighting-temperature cases.
- `PerspectiveCamera` lens presets: `wide_angle`, `standard`, `portrait`,
  `telephoto`, with `with_fov_degrees` as the explicit escape hatch.
- `Transform::looking_at` for facing a node at a target point.
- `DirectionalLight::sun`, `key_light`, `fill_light`, `rim_light`.
- `PointLight::softbox`, `bulb_warm`, `bulb_cool`.
- `MaterialDesc::matte`, `plastic`, `metal`, `rubber` — the four PBR
  presets the renderer can back today (glass/chrome/leather remain
  deferred until transmission/SSR/sheen ship the visual claim).
- `Background` enum: `Studio`, `DarkStudio`, `NeutralGray`, `White`,
  `Black`, `Sky`, `Transparent`, `Custom(Color)`, plus
  `Renderer::set_background`.
- `OrbitControls` named damping/auto-rotate presets: `cinematic`,
  `snappy`, `presentation`, `turntable(rpm)`, plus
  `zoom_limits_bounds_relative` for framing-relative zoom clamps.
- `AutoExposureConfig` scenario presets: `product_studio`, `indoor`,
  `outdoor`, `mixed`.

## Bundled Content And One-Call Helpers

- `EnvironmentPreset` catalog (`NeutralStudio`, `Studio`) with checked
  license/source/SHA-256 metadata plus `Assets::load_environment_preset`.
- `Assets::khronos()` Khronos sample loader (`KhronosSample`,
  `KhronosSamples`, `KhronosSampleMetadata`) with one-call shortcuts
  `water_bottle`, `transmission_test`, `rigged_simple` (feature
  `khronos-samples`).
- `Scene::play_animation_by_name(&import, "idle")` plus viewer-level
  `play_clip` sugar.
- `Scene::add_perspective_camera_default_for(bounds, viewport)` so the
  common load → frame → camera path is one call.
- `ConnectOptions::with_axial_gap` for editor-style drag-to-assemble.

## Viewer Ergonomics

- Pointer callbacks: `InteractiveGltfViewer::on_click`, `on_hover`,
  `clear_click_callback`, `clear_hover_callback`, plus asset-aware
  `pick_at`, `click_at`, `hover_at`, `pick_and_select_at`,
  `pick_and_hover_at`.
- Screenshot one-liners: `HeadlessGltfViewer::capture_png` /
  `capture_png_bytes`, `InteractiveGltfViewer::capture_png` /
  `capture_png_bytes`, `FirstRender::capture_png` /
  `capture_png_bytes`, and the no-GPU `HeadlessGltfViewerBuilder::render_png`
  / `render_png_bytes` one-shot path. Structured errors
  `ViewerCaptureError` and `ViewerPngError`.
- Native asset hot reload: `Assets::watch_scene_for_hot_reload`,
  `AssetHotReloadWatcher`, `AssetHotReloadError` (feature `hot-reload`).
- URL state sharing: `CameraOrbitUrlState`.

## `<scena-viewer>` Custom Element

This release ships the foundation for `<model-viewer>` attribute parity
in the browser: `defineScenaViewer()`, a shadow-canvas custom element
with model-viewer-style attribute parsing, drag-and-drop ingestion,
loading progress UI, material variant picker, slotted annotation
overlay, inspector overlay, mobile gesture handling, and accessibility
defaults. The M6 browser proof records `<scena-viewer>` / `<model-viewer>`
three-asset side-by-side parity for `WaterBottle`, `AnimatedMorphCube`,
and `non_ndc_camera_scene.gltf`.

## Renderer Features

- Anti-aliasing toggle: `AntiAliasing` + `Renderer::set_anti_aliasing`.
  FXAA stays the default; the explicit `None` setting gives deterministic
  pixel output for ON/OFF visual proof.
- Subtle bloom: `PostBloomConfig` + `Renderer::set_bloom` /
  `clear_bloom`.
- Headless CPU screen-space ambient occlusion:
  `ScreenSpaceAmbientOcclusionConfig` +
  `Renderer::set_screen_space_ambient_occlusion` / clear.
- Weighted-blended order-independent transparency:
  `OrderIndependentTransparencyConfig` +
  `Renderer::set_order_independent_transparency` / clear.
- Material extension coverage: clearcoat, sheen, anisotropy,
  iridescence, dispersion, transmission, IOR, and volume factors plus
  texture slots on `MaterialDesc`; CPU/reference rendering carries every
  lobe and WebGPU/WebGL2 shader variants carry clearcoat, sheen,
  anisotropy, iridescence, and dispersion punctual-light lobes.
- Wide-gamut output: `OutputColorSpace`,
  `RendererOptions::with_output_color_space`, capability reporting via
  `Capabilities::wide_gamut_output`, and a Display P3 browser proof.
- Asset doctor: `cargo run -p xtask -- asset-doctor <asset>` runs the
  official Khronos glTF Validator and emits
  `scena.asset_doctor.v1` JSON with renderer-aware `fix` strings.
  `GltfExtensionDiagnostic::suggested_fix` exposes the same remediation
  through library diagnostics.

## Documentation And Examples

- New / extended guide content in `docs/guides/easy-scene-setup.md` and
  `docs/guides/migrating-from-threejs.md` for the named primitives.
- `docs/api.md` lists every additive change.
- `examples/transform_escape_hatch.rs` teaches when raw `Quat::from_*`
  is appropriate.
- README updated with the new install snippet and v1.4 release-notes
  link.

## Proof Required Before Publication

- All `round_a_*`, `round_b_*`, `round_c_*`, `round_d_*` test suites pass.
- M2/M6/M8 visual artifacts present under
  `target/gate-artifacts/m2-visual/`, `m8-visual/`,
  `examples-visual/`, and the M6 browser-proof PNG / JSON family.
- Standard release gates: format, clippy, tests, doctor, claim audit,
  docs, and `cargo publish --dry-run`.
