softbox 4.24.0 → 4.25.1

package/README.md

@@ -25,7 +25,7 @@
 
 Balanced studio lighting, a baked soft contact shadow that grounds the model, auto-framing, compressed-asset decoders — all on by default, zero configuration (the real-scale concrete paver floor is [one option away](#configuration)). Lighting needs zero network requests (the studio environment is procedural); the DRACO/KTX2 decoder wasm is fetched only when a model actually uses that compression, from a CDN by default or [self-hosted](#loaders) for offline use. The core is ~102 kB gzip; the path tracer lives in a lazy chunk that loads only when enabled. Every release is gated by 790+ unit tests plus a Playwright suite that asserts **real WebGL pixels** in CI.
 
-[![softbox playground](https://raw.githubusercontent.com/LEMing/softbox/main/public/og-image.png)](https://leming.github.io/softbox/)
+[![softbox playground](https://raw.githubusercontent.com/LEMing/softbox/main/public/og-image.jpg)](https://leming.github.io/softbox/)
 
 **▶ [Live playground](https://leming.github.io/softbox/)** — drag & drop your own `.glb`, switch presets live, click the model to pin hotspots, download a still.
 
@@ -37,6 +37,7 @@ Balanced studio lighting, a baked soft contact shadow that grounds the model, au
 - **[Animations](#animations)** — GLTF clips autoplay with one word; play/pause/clip-picker API
 - **[Material variants](#material-variants)** — KHR_materials_variants colorways, switched live with one option
 - **[AR](#ar)** — one option hands the model to AR Quick Look (iOS) / Scene Viewer (Android)
+- **[Poster](#poster)** — an image is the instant first paint; the live model dissolves in when ready
 - **[Photoreal mode](#photoreal-mode--stills)** — progressive path tracing + `captureStill()` PNG export
 - **[Video capture](#video-capture)** — `captureVideo()` records the canvas to WebM/MP4, zero dependencies
 - **[Hotspots & click selection](#hotspot-annotations--click-selection)** — DOM pins on world-space points, BVH-accelerated picking
@@ -167,6 +168,24 @@ platform's native AR viewer — no WebXR session, no extra bundle:
 built-in preset picker on its own). UI-only: toggling `ar` never rebuilds
 the viewer or reloads the model.
 
+## Poster
+
+A poster image is the viewer's **instant first paint** — shown until the
+model's first painted frame, then dissolved into the live scene:
+
+```tsx
+<SimpleViewer object={url} options={{ poster: '/hero.webp', loading: 'lazy' }} />
+```
+
+With `loading: 'lazy'` the combination is LCP-friendly: the page paints the
+poster immediately with zero WebGL work, and the real viewer boots only
+when scrolled into view. Generate posters with `handle.captureStill()` —
+same studio look, pixel-identical to what the live viewer will show. While
+opaque, the poster catches input (nothing invisible underneath can be
+tapped). If the load fails, the poster stays up as the backdrop under the
+built-in error overlay — with `loadingIndicator: false` it steps aside
+instead, so a dead load never masquerades as a frozen hero image.
+
 ## Turntable
 
 One word puts the model on a slowly rotating showcase turntable. It pauses while the user drags and resumes on release; toggling is live, like presets.

package/dist/index.d.cts

@@ -757,6 +757,15 @@ export declare interface SimpleViewerOptions {
      * live preset picker). All opt-in; UI-only — never rebuilds the viewer.
      */
     ui?: UIOptions;
+    /**
+     * Poster image (URL) shown over the canvas until the model's first painted
+     * frame. Composes with `loading: 'lazy'`: the poster is the instant,
+     * WebGL-free first paint while the real viewer boots and the GLB
+     * downloads. Generate one with `handle.captureStill()`. Stays up as the
+     * backdrop if the load errs (the error overlay renders above it).
+     * UI-only — changing it never rebuilds the viewer.
+     */
+    poster?: string;
     /**
      * AR handoff button: opens the model in the platform's native AR viewer —
      * AR Quick Look on iOS (needs `iosSrc`, a USDZ counterpart), Scene Viewer

package/dist/index.d.ts

@@ -757,6 +757,15 @@ export declare interface SimpleViewerOptions {
      * live preset picker). All opt-in; UI-only — never rebuilds the viewer.
      */
     ui?: UIOptions;
+    /**
+     * Poster image (URL) shown over the canvas until the model's first painted
+     * frame. Composes with `loading: 'lazy'`: the poster is the instant,
+     * WebGL-free first paint while the real viewer boots and the GLB
+     * downloads. Generate one with `handle.captureStill()`. Stays up as the
+     * backdrop if the load errs (the error overlay renders above it).
+     * UI-only — changing it never rebuilds the viewer.
+     */
+    poster?: string;
     /**
      * AR handoff button: opens the model in the platform's native AR viewer —
      * AR Quick Look on iOS (needs `iosSrc`, a USDZ counterpart), Scene Viewer