softbox 4.23.0 → 4.25.0

package/README.md

@@ -36,6 +36,8 @@ Balanced studio lighting, a baked soft contact shadow that grounds the model, au
 - **[Turntable](#turntable)** — one-word showcase auto-rotate that pauses while the user drags
 - **[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
@@ -139,6 +141,51 @@ pick survives unrelated option changes. Variant materials materialize in
 the background right after load (first paint never waits for colorways
 nobody opened); an early pick is applied the moment they're ready.
 
+## AR
+
+One option puts an **AR** button over the canvas that opens the model in the
+platform's native AR viewer — no WebXR session, no extra bundle:
+
+```tsx
+<SimpleViewer object={url} options={{ ar: true }} />
+
+// iOS AR Quick Look cannot read GLB — give it the USDZ counterpart:
+<SimpleViewer object={url} options={{ ar: { iosSrc: '/shoe.usdz', title: 'Runner' } }} />
+```
+
+- **Android** → Scene Viewer, straight from the model's own URL (`ar: true`
+  is enough). The model must be loaded from an **https** URL — a dropped
+  `blob:` file has no address a native app could fetch, and Scene Viewer
+  refuses plain http. Imperative `loadModel()` swaps are tracked — the
+  button always hands off the model that is on stage.
+- **iOS** → AR Quick Look, from `iosSrc` (USDZ).
+- **Desktop / unsupported** → the button simply never renders, so setting
+  `ar` unconditionally is safe. On an Android-UA device that turns out to
+  have no AR component (Quest, TV boxes), the failed handoff bounces back
+  reload-free and the button retires itself.
+
+`placement` picks the corner (`bottom-left` by default; it lifts above the
+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

@@ -31,6 +31,33 @@ export declare interface AnimationOptions {
     speed?: number;
 }
 
+/**
+ * AR handoff configuration: a small button over the canvas that opens the
+ * model in the platform's native AR viewer — AR Quick Look on iOS, Scene
+ * Viewer on Android. UI-only: the button never touches the WebGL viewer, and
+ * toggling it never rebuilds anything. The button only renders on devices
+ * that can actually hand off (never on desktop).
+ */
+export declare interface AROptions {
+    /**
+     * USDZ counterpart of the model, for iOS AR Quick Look — Quick Look cannot
+     * read GLB, so without this the button stays hidden on iOS. Android Scene
+     * Viewer instead reuses the loaded model's own URL and needs nothing here
+     * (but requires the model to be loaded from a network URL — a dropped
+     * `blob:` file has no address a native app could fetch).
+     */
+    iosSrc?: string;
+    /** Title shown on Android Scene Viewer's info card. */
+    title?: string;
+    /**
+     * Corner the button floats in (default `bottom-left`). When the built-in
+     * preset picker is enabled, a bottom-placed button lifts above the chip
+     * row on its own — pick a top corner if it must clear other chrome (e.g.
+     * a `bottom-left` gizmo).
+     */
+    placement?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+
 export declare interface AxesHelperOptions {
     size?: number;
 }
@@ -730,6 +757,23 @@ 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
+     * on Android (reuses the model's own URL). `true` enables with defaults.
+     * The button renders only on devices that can actually hand off, so it is
+     * safe to set unconditionally. UI-only — never rebuilds the viewer.
+     */
+    ar?: boolean | AROptions;
     /**
      * Click-picking / hotspot-occlusion raycast tuning (e.g. `selection: { bvh:
      * false }` to skip the load-time BVH build on memory-constrained targets).

package/dist/index.d.ts

@@ -31,6 +31,33 @@ export declare interface AnimationOptions {
     speed?: number;
 }
 
+/**
+ * AR handoff configuration: a small button over the canvas that opens the
+ * model in the platform's native AR viewer — AR Quick Look on iOS, Scene
+ * Viewer on Android. UI-only: the button never touches the WebGL viewer, and
+ * toggling it never rebuilds anything. The button only renders on devices
+ * that can actually hand off (never on desktop).
+ */
+export declare interface AROptions {
+    /**
+     * USDZ counterpart of the model, for iOS AR Quick Look — Quick Look cannot
+     * read GLB, so without this the button stays hidden on iOS. Android Scene
+     * Viewer instead reuses the loaded model's own URL and needs nothing here
+     * (but requires the model to be loaded from a network URL — a dropped
+     * `blob:` file has no address a native app could fetch).
+     */
+    iosSrc?: string;
+    /** Title shown on Android Scene Viewer's info card. */
+    title?: string;
+    /**
+     * Corner the button floats in (default `bottom-left`). When the built-in
+     * preset picker is enabled, a bottom-placed button lifts above the chip
+     * row on its own — pick a top corner if it must clear other chrome (e.g.
+     * a `bottom-left` gizmo).
+     */
+    placement?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+}
+
 export declare interface AxesHelperOptions {
     size?: number;
 }
@@ -730,6 +757,23 @@ 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
+     * on Android (reuses the model's own URL). `true` enables with defaults.
+     * The button renders only on devices that can actually hand off, so it is
+     * safe to set unconditionally. UI-only — never rebuilds the viewer.
+     */
+    ar?: boolean | AROptions;
     /**
      * Click-picking / hotspot-occlusion raycast tuning (e.g. `selection: { bvh:
      * false }` to skip the load-time BVH build on memory-constrained targets).