@liveroom-tech/react-immersive 3.0.0 → 4.0.1

package/README.md

@@ -1,6 +1,8 @@
-# `@liveroom-tech/react-immersive`
+# React Immersive — 3D model viewer for React
 
-`@liveroom-tech/react-immersive` is a React-based 3D model viewer for interactive GLB/GLTF assets. It renders a model with React Three Fiber, lets users click named meshes, shows a built-in side panel for the selected object, and supports per-object actions such as color changes, texture uploads, and visibility toggles.
+`@liveroom-tech/react-immersive` is a React-based 3D model viewer for interactive GLB, GLTF, OBJ, FBX, and USDZ assets. It renders a model with React Three Fiber, lets users click named meshes, shows a built-in side panel for the selected object, and supports per-object actions such as color changes, texture uploads, and visibility toggles.
+
+[Website](https://react-immersive.liveroom.dev) · [Documentation](https://react-immersive.liveroom.dev/docs) · [Live editor](https://react-immersive.liveroom.dev/editor) · [npm](https://www.npmjs.com/package/@liveroom-tech/react-immersive) · [GitHub](https://github.com/Liveroom-Technologies/react-immersive-docs)
 
 ## What It Does
 
@@ -31,11 +33,12 @@ import {
 } from "@liveroom-tech/react-immersive";
 ```
 
-It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindingsController`, `ObjectActionEvent`, `SceneConfig`, `SceneConfigPatch`, `SceneConfigController`, `AnimationControls`, `CinematicConfig` / `CinematicWaypoint`, and related shapes used throughout this document.
+It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindingsController`, `ObjectActionEvent`, `ObjectTransformSpace`, `SceneConfig`, `SceneConfigPatch`, `SceneConfigController`, `AnimationControls`, `CinematicConfig` / `CinematicWaypoint`, and related shapes used throughout this document.
 
 `ModelViewer` provides:
 
-- GLB/GLTF model rendering through `@react-three/fiber` and `@react-three/drei`
+- GLB/GLTF, OBJ/MTL, FBX, and USDZ model rendering through `@react-three/fiber`
+- camera-driven 3D Tiles streaming through `tilesetUrl`, with configurable screen-space error and bounded tile cache
 - orbit/pan/zoom camera controls via `CameraControls`
 - auto-fits the model on load, and re-fits when the canvas is resized (window resize, device rotation, or a panel opening/closing), toggleable through `refitOnResize` to instead preserve the user's orbit/zoom
 - optional custom scene lighting through a `lights` prop
@@ -43,10 +46,13 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - optional custom background color through a `backgroundColor` prop
 - optional shadow rendering toggle through a `shadows` prop (on by default)
 - optional on-screen movement controller through `showMouseController` and its tuning props
+- optional canvas-focused keyboard camera navigation through `enableKeyboardNavigation`
+- optional top-right camera orientation control through `showViewGizmo`
+- optional per-object move and rotate gizmo through `moveModeEnabled`, with World/Local axis alignment through `objectTransformSpace`
 - optional custom left object data panel through `customObjectBindingDataPanel`
 - optional custom right scene objects panel through `customSceneObjectsPanel`
 - optional hiding of either built-in panel through `showObjectBindingDataPanel` and `showSceneObjectsPanel`
-- optional model export button through `showDownloadButton` and `downloadFilename`, plus an independent `showResetButton` toggle for the rest of that action bar
+- optional model export button through `showDownloadButton` and `downloadFilename`, opt-in PNG capture through `preserveDrawingBuffer`, plus an independent `showResetButton` toggle for the rest of that action bar
 - an optional UV Checker toolbar button through `showUvCheckerButton`, for inspecting UV scale, stretching, seams, orientation, and missing UV0 coordinates directly in `ModelViewer`
 - click-to-measure distance tool and a bounding-box dimensions overlay through `showMeasureTools` and `measurementUnit`
 - an exploded-view slider that slides each bound part outward from the model center to reveal interior/assembly structure through `showExplodeControls`
@@ -72,14 +78,15 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - camera change callbacks through `onCameraChange`
 - viewer-ready callbacks through `onViewerReady`
 - action event callbacks through `onAction`
-- animation playback for GLB/GLTF models with embedded animations through `onAnimationsReady`
+- animation playback for GLB/GLTF, FBX, and USDZ models with supported embedded animations through `onAnimationsReady`
 - annotation marker callbacks through `onAnnotationsChange` and controlled/uncontrolled `activeAnnotation` / `onActiveAnnotationChange`
 
 `BindingBuilder` provides:
 
-- a design-time UI for generating starter bindings from GLB/GLTF assets, gated by `licenseKey` (see "`BindingBuilder` licensing & plan tiers" below)
-- demo model loading or custom `.glb`, `.gltf`, or zipped GLTF upload
+- a design-time UI for generating starter bindings from GLB, GLTF, OBJ, FBX, and USDZ assets, gated by `licenseKey` (see "`BindingBuilder` licensing & plan tiers" below)
+- demo model loading or custom `.glb`, `.gltf`, `.obj`, `.fbx`, `.usdz`, or model ZIP bundle upload
 - editable binding fields for identity, basics, style, actions, metrics, metadata, and saved camera state
+- per-object move and rotate authoring with a geometry-centered pivot, World/Local axes, numeric fields, and restore-to-authored-transform support
 - a one-click material preset gallery (wood, metal, chrome, glass, plastic, fabric, ceramic, concrete, etc.)
 - undo/redo for both the Object tab's bindings and the Scene tab's config, independently, with `Cmd/Ctrl+Z` / `Cmd/Ctrl+Shift+Z` shortcuts
 - a Scene tab for the same `sceneConfig` shape `ModelViewer` accepts (lighting, environment, background, post-processing, animations, annotations, and cinematic camera paths)
@@ -91,8 +98,8 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 
 `SimpleModelViewer` provides:
 
-- a lightweight GLB/GLTF viewer that does not require `objectBindings` and does not require a `licenseKey`
-- optional local `.glb`, standalone/data-URI `.gltf`, or zipped GLTF upload mode for ad-hoc inspection without relying on the `modelUrl` asset
+- a lightweight GLB/GLTF/OBJ/FBX/USDZ viewer that does not require `objectBindings` and does not require a `licenseKey`
+- optional local `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, `.usdz`, or model ZIP bundle upload mode for ad-hoc inspection without relying on the `modelUrl` asset
 - built-in scene objects panel with search and visibility toggles
 - a built-in environment/scene settings panel (background color, environment preset, auto-rotate, exposure, ambient + directional light) toggleable via `showSceneSettingsPanel`, with each control's initial value seedable via props
 - click-to-select and fit-to-object focus behavior
@@ -112,7 +119,7 @@ domain model. It is a serializable record, keyed by mesh node name, that lets
 you:
 
 - declare which meshes are interactive
-- carry live render state such as visibility and per-object material overrides
+- carry live render state such as visibility, local transforms, and per-object material overrides
 - attach actions like `change-color`, `change-material`, and `toggle-visibility`
 - store metadata and metrics alongside the 3D scene
 - save camera framing so object focus can use curated views
@@ -161,7 +168,16 @@ has its own meaning, state, or behavior," object bindings are a strong fit.
 npm install @liveroom-tech/react-immersive
 ```
 
-The component ships with its own internal UI styles through a CSS import. Tailwind is not required in the consuming app.
+Import the library stylesheet once from your application root (for example,
+Next.js `app/layout.tsx`):
+
+```tsx
+import "@liveroom-tech/react-immersive/styles.css";
+```
+
+The styles ship as a static CSS file rather than a runtime-injected `<style>`
+tag, so a strict CSP does not need `style-src 'unsafe-inline'`. Tailwind is not
+required in the consuming app.
 
 Peer dependencies:
 
@@ -174,7 +190,7 @@ Peer dependencies:
 
 - [Developer Portal](https://react-immersive.liveroom.dev), sign in, pick a plan, and generate a `licenseKey`
 - [Docs](https://react-immersive.liveroom.dev/docs), full reference for every component, hook, and prop
-- [Examples & community repo](https://github.com/liveroom-technologies/react-immersive), public docs source, starter examples, and community resources
+- [Examples & community repo](https://github.com/liveroom-technologies/react-immersive-docs/examples), public docs source, starter examples, and community resources
 - [Report a bug / request a feature](https://github.com/liveroom-technologies/react-immersive-docs/issues), for public bug reports, docs issues, and feature requests
 - [Discussions & Q&A](https://github.com/liveroom-technologies/react-immersive-docs/discussions), ask questions, share ideas, and compare approaches
 - [Private support / security](mailto:developers@liveroom.xyz?subject=React%20Immersive%20Support), for license, account, confidential customer, or security-sensitive issues
@@ -185,7 +201,6 @@ Peer dependencies:
 
 ```tsx
 import {
-  defineObjectBindings,
   ModelViewer,
   useObjectBinding,
   useObjectBindings,
@@ -196,6 +211,7 @@ import {
   useViewerModel,
   useViewerSelection,
 } from "@liveroom-tech/react-immersive";
+import { defineObjectBindings } from "@liveroom-tech/react-immersive/utils";
 
 const initialBindings = defineObjectBindings({
   CarBody: {
@@ -412,7 +428,10 @@ updateMetadata({ group: "lights" }, { state: "on" });
 
 When a parent or store owns the state, use the pure `selectBindings` and
 `selectBindingKeys` helpers for the same queries, and `patchBindings` to update
-all matches.
+all matches. Import these helpers from
+`@liveroom-tech/react-immersive/utils` when the module must remain usable from a
+React Server Component; the main entry continues to re-export them for
+backwards compatibility.
 
 The hook returns:
 
@@ -624,21 +643,52 @@ export default function App() {
 }
 ```
 
-`BindingBuilder` accepts one required prop:
+`BindingBuilder` accepts one required prop and the same optional decoder
+configuration as the viewers:
 
 ```ts
 type BindingBuilderProps = {
   licenseKey: string;
+  licenseValidationUrl?: string;
+  dracoDecoderPath?: string | false;
+  ktx2TranscoderPath?: string | false;
+  meshopt?: boolean;
+  project?: BindingBuilderProject | null;
+  onProjectChange?: (snapshot: BindingBuilderProjectSnapshot, origin: "local" | "remote") => void;
+  projectChangeDebounceMs?: number;
+  onModelUpload?: (file: File) => Promise<BindingBuilderProjectModel>;
+  onEditLeaseChange?: (featureId: string, editing: boolean) => void;
 };
 ```
 
+Pass `tilesetUrl` to `ModelViewer` for a processed 3D Tiles asset. The original
+`modelUrl` remains the durable source/fallback URL, but is not downloaded by the
+viewer while a tileset is present:
+
+```tsx
+<ModelViewer
+  modelUrl="https://assets.example.com/source/building.glb"
+  tilesetUrl="https://assets.example.com/tiles/building/tileset.json"
+  tilesErrorTarget={8}
+  tilesCacheSize={800}
+  licenseKey="your-license-key"
+  objectBindings={{}}
+/>
+```
+
+Tiles are a dynamic level-of-detail scene, so automatic mesh binding generation
+is intentionally disabled in streamed `BindingBuilder` projects. Scene settings
+remain editable. Per-part editing requires the conversion pipeline to provide a
+stable CAD/object catalog that can be mapped to tile feature metadata.
+
 `licenseKey` is validated the same way as `ModelViewer`'s (see [`licenseKey`](#licensekey) below). While the key is being checked, `BindingBuilder` renders a "Verifying license…" placeholder; if it's invalid, it renders an error message instead of the editor.
 
 Current behavior, Object tab:
 
-- load the bundled demo model or upload a `.glb`, standalone/data-URI `.gltf`, or `.zip` containing a `.gltf` plus its referenced `.bin` and texture files
+- upload a `.glb`, standalone/data-URI `.gltf`, or `.zip` containing a `.gltf` plus its referenced `.bin` and texture files
 - traverse renderable mesh nodes and generate starter bindings automatically
 - edit binding identity, label, type, status, booleans, style, actions, metrics, metadata, and saved camera state
+- move and rotate the selected object from the **Move & Rotate** panel using a geometry-centered pivot, World/Local axis alignment, or numeric position and degree fields; restore its authored transform with one click
 - apply a one-click material preset (wood, metal, chrome, glass, plastic, fabric, ceramic, concrete, etc.) onto the selected object's material
 - undo/redo the current bindings (toolbar buttons or `Cmd/Ctrl+Z` / `Cmd/Ctrl+Shift+Z`); rapid edits coalesce into a single undo step
 - import a previously exported `objectBindings.json`, merged onto the current model by `modelObjectId`
@@ -654,6 +704,7 @@ Current behavior, Scene tab:
 Preview:
 
 - the selected node previews live in an embedded `ModelViewer`
+- enable **Transform gizmo**, select a mesh, then use the arrows and plane handles to move it or the rings to rotate it; all changes are saved to `binding.transform`
 
 ### `BindingBuilder` licensing & plan tiers
 
@@ -669,7 +720,7 @@ A locked feature renders in place (not hidden) with a message naming the require
 
 ## `SimpleModelViewer`
 
-`SimpleModelViewer` is an exported lightweight viewer for cases where you want to load a GLB/GLTF asset, inspect meshes, and toggle visibility without building `objectBindings`. It can either load a fixed `modelUrl` or, when `enableModelUpload` is turned on, let the user drag-and-drop or choose a local model at runtime.
+`SimpleModelViewer` is an exported lightweight viewer for cases where you want to load a GLB, GLTF, OBJ, FBX, or USDZ asset, inspect meshes, and toggle visibility without building `objectBindings`. It can either load a fixed `modelUrl` or, when `enableModelUpload` is turned on, let the user drag-and-drop or choose a local model at runtime.
 
 Basic usage:
 
@@ -694,7 +745,7 @@ Sizing note:
 
 Current behavior:
 
-- discovers renderable meshes directly from the loaded GLB/GLTF scene
+- discovers renderable meshes directly from the loaded model scene
 - renders a right-side scene objects panel with search and visibility toggles
 - renders a left-side environment/scene settings panel (background color, environment preset, auto-rotate, exposure, ambient + directional light) toggleable via `showSceneSettingsPanel`, with every control seedable via props
 - optionally replaces `modelUrl` with a drag-and-drop / file-picker flow when `enableModelUpload` is enabled
@@ -831,8 +882,11 @@ const { clips, currentClip, isPlaying, play, pause, stop, setSpeed } =
 The source code currently defines `ModelViewer` with these props:
 
 ```ts
+type ObjectTransformSpace = "local" | "world";
+
 type Props = {
   modelUrl: string;
+  modelFormat?: "glb" | "gltf" | "obj" | "fbx" | "usdz";
   licenseKey: string;
   objectBindings: Record<string, ObjectBinding>;
   selectedObject?: ObjectBinding | null;
@@ -881,10 +935,15 @@ type Props = {
   sceneConfig?: SceneConfig;
   disableZoom?: boolean;
   zoomOnSelected?: boolean;
+  enableCameraControls?: boolean;
+  moveModeEnabled?: boolean;
+  objectTransformSpace?: ObjectTransformSpace;
+  enableKeyboardNavigation?: boolean;
   onAutoFit?: () => Promise<boolean>;
   refitOnResize?: boolean;
   renderMode?: "always" | "demand";
   maxDpr?: number;
+  preserveDrawingBuffer?: boolean;
   performanceProfile?: "auto" | "high" | "low";
   dracoDecoderPath?: string | false;
   ktx2TranscoderPath?: string | false;
@@ -900,12 +959,13 @@ type Props = {
   mobileHandoffUrl?: string;
   showAnnotationNavigation?: boolean;
   showAnnotationOnHover?: boolean;
+  showViewGizmo?: boolean;
 };
 ```
 
 ### `modelUrl`
 
-URL or public path to the `.glb` or `.gltf` model. For `.gltf` URLs with external `.bin` or texture files, those files must be hosted at the relative paths declared in the `.gltf`.
+URL or public path to a `.glb`, `.gltf`, `.obj`, `.fbx`, or `.usdz` model. Hosted GLTF, OBJ, and FBX assets must serve external buffers, MTL files, and textures at their declared relative paths. USDZ dependencies are contained in the USDZ package. Use `modelFormat` when a signed or extensionless URL cannot be auto-detected.
 
 Example:
 
@@ -913,6 +973,11 @@ Example:
 modelUrl = "/model.glb";
 ```
 
+### `modelFormat`
+
+Optional explicit format for signed or extensionless model URLs. Normal URLs
+ending in `.glb`, `.gltf`, `.obj`, `.fbx`, or `.usdz` are detected automatically.
+
 ### `licenseKey`
 
 License key for the library. Required.
@@ -932,7 +997,7 @@ A map keyed by the model node name. Each key should match a mesh name from the G
 Example:
 
 ```ts
-import { defineObjectBindings } from "@liveroom-tech/react-immersive";
+import { defineObjectBindings } from "@liveroom-tech/react-immersive/utils";
 
 const objectBindings = defineObjectBindings({
   Object_2: {
@@ -1008,6 +1073,7 @@ This fires for:
 - color picks (`binding.style.material.baseColor`), committed when the color picker closes
 - texture uploads (`binding.style.material.texture.path`), committed immediately (via `onTextureUpload` when provided, otherwise as a blob URL)
 - texture removal (`binding.style.material.texture` cleared)
+- object movement and rotation (`binding.transform.position` and `binding.transform.rotation`)
 
 If you want the viewer and your app state to stay in sync, pass `objectBindings` from state and wire this callback back into that state setter.
 
@@ -1077,16 +1143,19 @@ type CaptureImageOptions = {
 };
 ```
 
-`captureImage` forces a render and resolves with a `data:image/png` URL. Pass `width`/`height` to render at a resolution other than the canvas's current size, and `transparent` to hide the configured background so the PNG carries an alpha channel instead. It rejects if called before the viewer is ready.
+`captureImage` requires the opt-in `preserveDrawingBuffer` prop, forces a render, and resolves with a `data:image/png` URL. Pass `width`/`height` to render at a resolution other than the canvas's current size, and `transparent` to hide the configured background so the PNG carries an alpha channel instead. It rejects if called before the viewer is ready or when framebuffer preservation is disabled. The Download PNG menu item is also shown only when this prop is enabled.
 
 ```tsx
-onViewerReady={(viewer) => {
-  viewer
-    .captureImage({ width: 1920, height: 1080, transparent: true })
-    .then((dataUrl) => {
-      // upload, preview, etc.
-    });
-}}
+<ModelViewer
+  preserveDrawingBuffer
+  onViewerReady={(viewer) => {
+    viewer
+      .captureImage({ width: 1920, height: 1080, transparent: true })
+      .then((dataUrl) => {
+        // upload, preview, etc.
+      });
+  }}
+/>;
 ```
 
 Note: requesting a custom `width`/`height` briefly resizes the live canvas to render at that resolution before restoring it, which can cause a momentary flicker on screen, fine for an occasional snapshot, not for rapid/looped calls.
@@ -1098,7 +1167,10 @@ const camera = useViewerCamera();
 const effects = useViewerEffects();
 const connection = useViewerConnection(camera, effects);
 
-<ModelViewer onViewerReady={connection.handleViewerReady} />;
+<ModelViewer
+  preserveDrawingBuffer
+  onViewerReady={connection.handleViewerReady}
+/>;
 
 const dataUrl = await connection.captureImage({ width: 1920, height: 1080 });
 ```
@@ -1336,8 +1408,9 @@ true;
 
 ### `showDownloadButton`
 
-Optional boolean that enables the download split-button (export GLB, export PNG
-screenshot, or export the model's UV layout).
+Optional boolean that enables the download split-button (export GLB, export the
+model's UV layout, and—when `preserveDrawingBuffer` is enabled—export a PNG
+screenshot).
 
 Default:
 
@@ -1495,6 +1568,82 @@ Default:
 true;
 ```
 
+### Moving and rotating objects
+
+Set `moveModeEnabled` to show a centered Drei `PivotControls` gizmo for the
+selected bound object. Translation arrows, plane handles, and rotation rings
+are available together; scaling is not enabled. While object editing is on,
+the camera controls are paused so pointer drags manipulate the object instead
+of the camera.
+
+```tsx
+import { useState } from "react";
+import {
+  ModelViewer,
+  type ObjectBinding,
+} from "@liveroom-tech/react-immersive";
+
+export function EditableViewer({
+  initialBindings,
+}: {
+  initialBindings: Record<string, ObjectBinding>;
+}) {
+  const [objectBindings, setObjectBindings] = useState(initialBindings);
+
+  return (
+    <ModelViewer
+      modelUrl="/model.glb"
+      licenseKey="your-license-key"
+      objectBindings={objectBindings}
+      onObjectBindingsChange={setObjectBindings}
+      moveModeEnabled
+      objectTransformSpace="world"
+    />
+  );
+}
+```
+
+Click a bound mesh to select it, then drag an arrow to move on one axis, a
+plane handle to move on two axes, or a ring to rotate. The pivot is placed at
+the center of the selected object's renderable geometry, so rotation happens
+around the object itself even when the source model's node origin is elsewhere.
+
+`objectTransformSpace` accepts:
+
+- `"world"` (default): the gizmo remains aligned with the scene axes
+- `"local"`: the gizmo follows the selected object's current orientation
+
+Axis space changes the direction of the handles; it does not change the
+object's position when toggled. The resulting `transform.position` and
+`transform.rotation` values are always persisted in the object's local space,
+with rotation stored in radians.
+
+Passing `onObjectBindingsChange` makes binding edits controlled, so the parent
+must store the returned record as shown above. Without that callback,
+`ModelViewer` keeps edits internally for the mounted viewer. Similarly, when
+you pass `selectedObject`, update it from `onObjectSelect`; otherwise selection
+is managed internally.
+
+### `enableCameraControls`
+
+Optional boolean controlling orbit, pan, and zoom input. Default: `true`.
+Camera controls are temporarily disabled whenever `moveModeEnabled` is on.
+
+### `enableKeyboardNavigation`
+
+Optional boolean enabling camera shortcuts after the viewer canvas is clicked
+or focused. Default: `false`. Use `W`/`S` to move forward/back, `A`/`D` to
+truck left/right, Space/`C` to move up/down, and the arrow keys to orbit.
+`Shift` + Up/Down moves forward/back. Keyboard navigation is inactive while
+object editing or camera controls are disabled.
+
+### `showViewGizmo`
+
+Optional boolean showing a clickable orientation gizmo in the top-right of the
+viewer. Default: `false`. It indicates the camera's view of the scene axes and
+can snap the camera to an axis; it is separate from the selected object's
+transform gizmo and is hidden while `moveModeEnabled` is on.
+
 ### `onAutoFit`
 
 Optional async callback fired once the model has loaded and the scene is ready. When provided, the viewer calls it so consumers can run their own fit-to-scene behavior (e.g. an animated fit); if omitted, the viewer falls back to its internal `fitScene`, unless an explicit [`camera`](#camera) prop was given, in which case that position is treated as the chosen initial view and `fitScene` is skipped.
@@ -1562,6 +1711,18 @@ Default:
 2;
 ```
 
+### `preserveDrawingBuffer`
+
+Optional boolean that retains the WebGL framebuffer for PNG screenshots. It is
+`false` by default to avoid imposing framebuffer-retention cost on every frame.
+Enable it when using `captureImage` or the built-in Download PNG action.
+
+Default:
+
+```ts
+false;
+```
+
 ### `performanceProfile`
 
 Optional control over how aggressively the viewer trades visual fidelity for a stable WebGL context on constrained GPUs.
@@ -1590,7 +1751,43 @@ ktx2TranscoderPath?: string | false;
 meshopt?: boolean;
 ```
 
-DRACO, Meshopt, and KTX2 decoding are enabled by default via hosted decoder/transcoder bundles, fetched lazily only when the model needs them. Pass a path to self-host the decoder/transcoder files, or `false` to disable that decoder.
+Meshopt is bundled and enabled by default. DRACO and KTX2 are also enabled by
+default through immutable, versioned decoder builds hosted on the first-party
+`assets.react-immersive.liveroom.dev` domain. They are fetched lazily only when a model
+uses the corresponding compression format.
+
+```ts
+dracoDecoderPath =
+  "https://assets.react-immersive.liveroom.dev/three-r184/draco/";
+ktx2TranscoderPath =
+  "https://assets.react-immersive.liveroom.dev/three-r184/basis/";
+```
+
+Pass `false` to disable either decoder. For a fully self-hosted or offline
+deployment, version-matched files are included under `dist/decoders`.
+
+Copy those files into your app's public/static directory during deployment:
+
+```sh
+cp -R node_modules/@liveroom-tech/react-immersive/dist/decoders public/react-immersive-decoders
+```
+
+Then pass the public URL directories (including the trailing slash):
+
+```tsx
+<ModelViewer
+  dracoDecoderPath="/react-immersive-decoders/draco/"
+  ktx2TranscoderPath="/react-immersive-decoders/basis/"
+  {...props}
+/>
+```
+
+The same props are available on `SimpleModelViewer` and `BindingBuilder`. When
+using the built-in defaults with a strict CSP, allow the first-party asset
+origin and decoder workers; a typical baseline is
+`connect-src 'self' https://assets.react-immersive.liveroom.dev; worker-src 'self' blob:; script-src 'self' 'wasm-unsafe-eval'`.
+Self-hosted paths only require `'self'`. Older browsers may require their
+WebAssembly fallback policy as well.
 
 ### `showUvCheckerButton`
 
@@ -1795,6 +1992,10 @@ See the full variable list in the [`ModelViewer` docs](https://react-immersive.l
 ```ts
 type SimpleModelViewerProps = {
   modelUrl: string;
+  modelFormat?: "glb" | "gltf" | "obj" | "fbx" | "usdz";
+  dracoDecoderPath?: string | false;
+  ktx2TranscoderPath?: string | false;
+  meshopt?: boolean;
   backgroundColor?: string;
   showSceneObjectsPanel?: boolean;
   showSceneSettingsPanel?: boolean;
@@ -1821,7 +2022,12 @@ type SimpleModelViewerProps = {
 
 ### `modelUrl`
 
-URL or public path to the `.glb` or `.gltf` model to inspect. For `.gltf` URLs with external `.bin` or texture files, those files must be hosted at the relative paths declared in the `.gltf`.
+URL or public path to the `.glb`, `.gltf`, `.obj`, `.fbx`, or `.usdz` model to inspect. Hosted assets must serve external dependencies at their declared relative paths; USDZ dependencies are packaged internally. Use `modelFormat` when a signed or extensionless URL cannot be auto-detected.
+
+### `modelFormat`
+
+Optional explicit format for signed or extensionless model URLs. Normal URLs
+ending in a supported extension are detected automatically.
 
 ### `backgroundColor`
 
@@ -1924,7 +2130,7 @@ true;
 
 ### `enableModelUpload`
 
-Optional boolean that swaps the fixed `modelUrl` workflow for a built-in upload UI. When enabled, the viewer starts with a drag-and-drop / file-picker empty state and loads the uploaded `.glb`, standalone/data-URI `.gltf`, or `.zip` containing a `.gltf` plus its referenced `.bin` and texture files instead of the asset passed via `modelUrl`.
+Optional boolean that swaps the fixed `modelUrl` workflow for a built-in upload UI. It accepts `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, `.usdz`, or a `.zip` bundle. ZIP bundles may contain a GLTF with its buffers/textures, an OBJ with its optional MTL/textures, or an FBX with external textures. A USDZ file is already a self-contained package and is uploaded directly.
 
 Default:
 
@@ -1997,7 +2203,9 @@ Notes:
 - the `objectBindings` record is keyed by node name, not by `id`
 - `group` and `tags` can be assigned in `BindingBuilder` and used as targets by binding helpers and runtime material or transform effects
 - `visible` is live render state, not just an initial default
-- `transform` is persistent local-space render state; missing fields retain their model-authored values and removing it restores the authored transform
+- `transform` is persistent local-space render state; position values use model units and rotation values use radians
+- the transform gizmo is displayed at the center of the object's renderable geometry for intuitive rotation, even if the authored node origin is elsewhere; this does not rewrite the GLB/GLTF origin
+- missing transform fields retain their model-authored values, and removing `transform` restores the authored transform
 - `style.material.baseColor` is read by the renderer and is the committed source of truth for color picks
 - `style.material.texture.path` is read by the renderer and is the committed source of truth for texture uploads (stored as durable URLs via `onTextureUpload` when provided, or session-scoped blob URLs otherwise)
 - if no `texture.path` is provided and no `style.material.baseColor` is set, the viewer falls back to the node's original GLB/GLTF material
@@ -2062,11 +2270,13 @@ Because of that, it works best when mounted in a container with an explicit heig
 
 ## Usage Expectations For Models
 
-To use this library successfully, your GLB/GLTF asset should follow these expectations:
+To use this library successfully, your model asset should follow these expectations:
 
 - the mesh node names must match the keys in `objectBindings` (or be referenced via `modelObjectId`)
-- target nodes should have geometry and a `MeshStandardMaterial`
-- the file should be accessible from the browser at `modelUrl`; hosted `.gltf` files must also serve external `.bin` and texture files at their declared relative paths
+- target nodes should have geometry and a supported Three.js mesh material; imported materials are normalized into the editable PBR pipeline
+- the file should be accessible from the browser at `modelUrl`; hosted GLTF, OBJ, and FBX assets must also serve external dependencies at their declared relative paths
+- OBJ does not contain animations; supported FBX and USDZ animation clips are exposed through the same animation controls as glTF
+- OBJ has no standard unit metadata, so set an appropriate measurement label/scene scale when real-world dimensions matter
 
 If a node name or material name does not match, that object will not render through the interactive binding flow.