@preference-sl/pref-viewer 2.16.0-beta.14 → 2.16.0-beta.18

package/README.md

@@ -235,19 +235,23 @@ Storage descriptors are passed through `model.storage`, `scene.storage`, `materi
 
 | Method | Description |
 | --- | --- |
-| `setSelectableElements(elements)` | Defines which host element ids are selectable. Accepts strings or objects with `id`/`Id`. |
-| `setSelectedElements(elements)` | Defines selected elements. Accepts strings or objects with `id`/`Id` and optional `highlights`/`Highlights`. |
-| `applySelectionState(state)` | Applies selectable and selected state in one call. Accepts `selectableIds`/`selectables` and `selectedItems`/`selectedIds`/`selected`. |
+| `setSelectableElements(elements)` | Defines and renders selectable SVG ids in yellow (`#FFFF00`, opacity `0.5`). Accepts strings or objects with `id`/`Id`. |
+| `setSelectedElements(elements)` | Defines and renders selected highlights in red (`#FF0000`, opacity `0.5`). Accepts strings or objects with `id`/`Id` and optional `highlights`/`Highlights`. |
+| `applySelectionState(state)` | Applies selectable and selected state to the semantic snapshot and 2D drawing in one call. Accepts `selectableIds`/`selectables` and `selectedItems`/`selectedIds`/`selected`; state supplied before a drawing is reapplied after load. |
 | `clearSelectedElements()` | Clears selected elements while preserving the selectable set. |
 | `clearSelectableElements()` | Clears selectable elements while preserving the selected set. |
 | `clearSelectionState()` | Clears all semantic selection state. |
 | `getSelectionState()` | Returns `{ selectableIds, selectedIds, selectedItems }`. |
-| `notifyElementClick(element)` | Emits `pref-viewer-element-click` from a host-forwarded element id or detail object. |
+| `notifyElementClick(element)` | Emits `pref-viewer-element-click` with exactly `{ ids: string[] }` from a string, descriptor, collection, or `{ ids }` input. This replaces the provisional `detail.element` payload. |
+| `appendSvgNode(id, svgId, svg)` | Adds a host-owned SVG node to the interactive 2D drawing. The node's identified geometry participates in hit-testing and selection. Returns `false` for a duplicate `svgId` or absent node. |
+| `removeAppendedSvgNodes()` | Removes every SVG node previously added through `appendSvgNode` and reconciles the current visual selection layers. |
 | `startTurnable(options)` | Starts semantic turnable state and emits `pref-viewer-3d-turnable-changed`. |
 | `stopTurnable()` | Stops semantic turnable state. |
 | `toggleTurnable(options)` | Toggles semantic turnable state. |
 | `getTurnableState()` | Returns `{ running, speed, direction }`. |
 
+Selection colors are rendered through disposable SVG clones; the loaded base SVG and shared definitions are not modified. Selectable clones are inserted before selected clones so red selection remains visible above yellow availability. Reapplying state is idempotent, and replacing the drawing removes dynamic nodes and prior visual layers before the current semantic snapshot is rendered again.
+
 ### Animation controls
 
 | Method | Description |
@@ -309,7 +313,7 @@ The component emits custom events so host applications can integrate loading ind
 | `pref-viewer-loaded` | `<pref-viewer>` | None | A 2D or 3D load operation completed. Includes `detail.mode` with the current root mode. |
 | `pref-viewer-error` | `<pref-viewer>` | None | A 2D or 3D operation failed. Includes `detail.mode` with the current root mode. |
 | `pref-viewer-selection-state-changed` | `<pref-viewer>` | None | The semantic selection state changed. |
-| `pref-viewer-element-click` | `<pref-viewer>` | None | A selectable element was clicked or forwarded by the host integration. |
+| `pref-viewer-element-click` | `<pref-viewer>` | None | A semantic SVG element was clicked or forwarded by the host. Geometry without its own id resolves the nearest id-bearing ancestor inside the drawing. `detail` is exactly `{ ids: string[] }`; clicks are emitted independently of the current selectable set. |
 
 ### 3D Events
 

package/index.d.ts

@@ -1,24 +1,385 @@
 import type React from "react";
 
+/** Render mode. `loadConfig`/`loadDrawing` pick the matching one on their own. */
+export type PrefViewerMode = "2d" | "3d";
+
+/** Animation state as reported by `getAnimations()` and `prefviewer-animation-changed`. */
+export type PrefViewerAnimationState = 0 | 1 | 2 | 3 | 4;
+
+/** Action accepted by `playAnimation`. */
+export type PrefViewerAnimationAction = "open" | "close" | "pause" | "goToOpened" | "goToClosed";
+
+/**
+ * An IndexedDB pointer. The SDK writes the asset and hands you the record id;
+ * the viewer reads it back itself, so you never fetch or decode the bytes.
+ */
+export interface PrefViewerStoragePointer {
+  db: string;
+  table: string;
+  id: string;
+}
+
+/** A storage pointer or a plain URL — every asset slot accepts either. */
+export type PrefViewerSource = PrefViewerStoragePointer | { url: string };
+
+export interface PrefViewerAsset {
+  storage: PrefViewerSource;
+  visible?: boolean;
+}
+
+/** Payload for `loadConfig`. Pass the object; a JSON string is also accepted. */
+export interface PrefViewerConfig {
+  model?: PrefViewerAsset;
+  scene?: PrefViewerAsset;
+  materials?: PrefViewerAsset;
+  drawing?: PrefViewerAsset;
+  options?: Record<string, unknown>;
+}
+
+export interface PrefViewerAnimation {
+  name: string;
+  state: PrefViewerAnimationState;
+  progress: number;
+  loop: boolean;
+  nodes: string[];
+}
+
+/**
+ * `<pref-viewer>` shadows the standard `Element.getAnimations()` with its own snapshot of the
+ * model's opening animations. The two signatures are incompatible, so the method is not declared
+ * on `PrefViewer` — reach it through this view:
+ *
+ * ```ts
+ * const animations = (viewer as unknown as PrefViewerAnimationsApi).getAnimations()
+ * ```
+ */
+export interface PrefViewerAnimationsApi {
+  getAnimations(): PrefViewerAnimation[];
+}
+
+// ── Semantic selection and turnable state ──
+
+export interface PrefViewerSelectionItem {
+  id: string;
+  highlights: string[];
+}
+
+export interface PrefViewerSelectionDescriptor {
+  id?: string;
+  Id?: string;
+  highlights?: string[];
+  Highlights?: string[];
+}
+
+export interface PrefViewerSelectionState {
+  selectableIds: string[];
+  selectedIds: string[];
+  selectedItems: PrefViewerSelectionItem[];
+}
+
+export type PrefViewerElementDescriptor = string | { id?: string; Id?: string };
+
+export interface PrefViewerSelectionInput {
+  selectableIds?: PrefViewerElementDescriptor[];
+  selectables?: PrefViewerElementDescriptor[];
+  selectedItems?: Array<string | PrefViewerSelectionDescriptor>;
+  selectedIds?: PrefViewerElementDescriptor[];
+  selected?: Array<string | PrefViewerSelectionDescriptor>;
+}
+
+export interface PrefViewerElementClickDetail {
+  ids: string[];
+}
+
+/** Optional speed/direction for `startTurnable` / `toggleTurnable`. */
+export interface PrefViewerTurnableOptions {
+  speed?: number;
+  direction?: string;
+}
+
+export interface PrefViewerTurnableState {
+  running: boolean;
+  speed: number;
+  direction: string;
+}
+
+// ── Event details ──
+
+/** Which containers a load touched, and which of them succeeded. */
+export interface PrefViewerContainerFlags {
+  model?: boolean;
+  scene?: boolean;
+  materials?: boolean;
+}
+
+export interface PrefViewerSceneLoadedDetail {
+  tried: PrefViewerContainerFlags;
+  success: PrefViewerContainerFlags;
+}
+
+export interface PrefViewerSceneOptionsDetail {
+  success: boolean;
+  detail: PrefViewerSceneLoadedDetail;
+}
+
+export interface PrefViewerDrawingLoadedDetail {
+  success: boolean;
+  error: Error | null;
+}
+
+export interface PrefViewerErrorDetail {
+  error: Error;
+}
+
+export interface PrefViewerAnimationChangedDetail {
+  name: string;
+  state: PrefViewerAnimationState;
+  progress: number;
+  loop: boolean;
+}
+
+export interface PrefViewerInitializedDetail {
+  isInitialized: boolean;
+}
+
+/** The 2D pan/zoom viewport, as reported after every pan or zoom. */
+export interface PrefViewerViewportChangedDetail {
+  x: number;
+  y: number;
+  scale: number;
+  moved: boolean;
+  scaled: boolean;
+  maximized: boolean;
+  minimized: boolean;
+}
+
+/**
+ * Root-scoped events (`pref-viewer-loading` / `-loaded` / `-error`) fire for both modes and
+ * carry the mode they happened in; the 2D- and 3D-scoped events do not.
+ */
+export interface PrefViewerRootLoadingDetail {
+  mode: PrefViewerMode;
+}
+
+export interface PrefViewerRootLoadedDetail {
+  mode: PrefViewerMode;
+  result: PrefViewerSceneLoadedDetail | PrefViewerDrawingLoadedDetail | null;
+}
+
+export interface PrefViewerRootErrorDetail {
+  mode: PrefViewerMode;
+  error: Error | null;
+}
+
+/**
+ * Events dispatched by `<pref-viewer>`. All bubble and are composed, so a listener
+ * on an ancestor outside the shadow root still receives them.
+ *
+ * The `scene-*` / `drawing-*` names are the legacy aliases: each is still emitted
+ * alongside its `pref-viewer-3d-*` / `pref-viewer-2d-*` equivalent, with the same detail.
+ */
+export interface PrefViewerEventMap {
+  "pref-viewer-initialized": CustomEvent<PrefViewerInitializedDetail>;
+
+  // Root scope — either mode, and the detail says which.
+  "pref-viewer-loading": CustomEvent<PrefViewerRootLoadingDetail>;
+  "pref-viewer-loaded": CustomEvent<PrefViewerRootLoadedDetail>;
+  "pref-viewer-error": CustomEvent<PrefViewerRootErrorDetail>;
+
+  // 3D scope (and its legacy aliases).
+  "pref-viewer-3d-loading": CustomEvent<undefined>;
+  "pref-viewer-3d-loaded": CustomEvent<PrefViewerSceneLoadedDetail | Record<string, never>>;
+  "pref-viewer-3d-error": CustomEvent<PrefViewerErrorDetail | Record<string, never>>;
+  "pref-viewer-3d-turnable-changed": CustomEvent<{ state: PrefViewerTurnableState }>;
+  "scene-loading": CustomEvent<undefined>;
+  "scene-loaded": CustomEvent<PrefViewerSceneLoadedDetail | undefined>;
+  "scene-error": CustomEvent<PrefViewerErrorDetail>;
+
+  // 2D scope (and its legacy aliases).
+  "pref-viewer-2d-loading": CustomEvent<undefined>;
+  "pref-viewer-2d-loaded": CustomEvent<PrefViewerDrawingLoadedDetail | Record<string, never>>;
+  "pref-viewer-2d-error": CustomEvent<PrefViewerErrorDetail | Record<string, never>>;
+  "pref-viewer-2d-viewport-changed": CustomEvent<PrefViewerViewportChangedDetail>;
+  "pref-viewer-2d-element-click": CustomEvent<PrefViewerElementClickDetail>;
+  "drawing-loading": CustomEvent<undefined>;
+  "drawing-loaded": CustomEvent<PrefViewerDrawingLoadedDetail>;
+  "drawing-error": CustomEvent<PrefViewerErrorDetail>;
+  "drawing-zoom-changed": CustomEvent<{ zoom: number }>;
+
+  // Semantic selection.
+  "pref-viewer-element-click": CustomEvent<PrefViewerElementClickDetail>;
+  "pref-viewer-selection-state-changed": CustomEvent<PrefViewerSelectionState>;
+
+  /** Re-dispatched from the 3D component; not emitted by the root element. */
+  "prefviewer-animation-changed": CustomEvent<PrefViewerAnimationChangedDetail>;
+}
+
 export declare class PrefViewer extends HTMLElement {
-  /**
-   * The URL or blob string of the GLTF model
-   */
-  set model(v: string | null);
+  // ── Property setters (each mirrors the attribute of the same name) ──
+  set config(v: PrefViewerConfig | string | null);
+  set culture(v: string | null);
+  set drawing(v: PrefViewerAsset | string | null);
+  set materials(v: PrefViewerAsset | string | null);
+  set mode(v: PrefViewerMode | null);
+  /** The URL or storage pointer of the glTF model. */
+  set model(v: PrefViewerAsset | string | null);
+  set options(v: Record<string, unknown> | string | null);
+  set scene(v: PrefViewerAsset | string | null);
+  /** Supported style overrides; currently `{ colorPrimary }`. */
+  set styles(v: Record<string, unknown> | string | null);
+
+  // ── Read-only state ──
+  get culture(): string;
+  get isInitialized(): boolean;
+  get isLoaded(): boolean;
+  get isLoading(): boolean;
+
+  // ── Loading ──
+  /** Returns false when the config is unusable; otherwise queues the work. */
+  loadConfig(config: PrefViewerConfig | string): boolean | void;
+  loadDrawing(drawing: PrefViewerAsset | string): boolean | void;
+  loadMaterials(materials: PrefViewerAsset | string): boolean | void;
+  loadModel(model: PrefViewerAsset | string): boolean | void;
+  loadScene(scene: PrefViewerAsset | string): boolean | void;
+
+  // ── Runtime ──
+  setCulture(cultureId: string): void;
+  setMode(mode?: PrefViewerMode): void;
+  /** Cheaper than a full `loadConfig` when only options changed — no visible reload. */
+  setOptions(options: Record<string, unknown> | string): void;
+  /** Convenience wrapper for `setOptions({ ibl })`. False when the payload is unusable. */
+  setIBL(ibl: Record<string, unknown> | string): boolean | void;
+  /** Runtime style overrides; currently `{ colorPrimary }`. False when unusable. */
+  setStyles(styles: Record<string, unknown> | string): boolean | void;
+  /** 3D runtime diagnostics, or null before the 3D component exists. */
+  getDebugInfo(): Record<string, unknown> | null;
+
+  // ── Visibility and framing ──
+  showModel(): void;
+  hideModel(): void;
+  showScene(): void;
+  hideScene(): void;
+  zoomCenter(): void;
+  zoomExtentsAll(): void;
+  zoomIn(): void;
+  zoomOut(): void;
+
+  // ── Semantic selection ──
+  setSelectableElements(elements?: PrefViewerElementDescriptor[]): PrefViewerSelectionState;
+  setSelectedElements(elements?: Array<string | PrefViewerSelectionDescriptor>): PrefViewerSelectionState;
+  applySelectionState(state?: PrefViewerSelectionInput): PrefViewerSelectionState;
+  clearSelectedElements(): PrefViewerSelectionState;
+  clearSelectableElements(): PrefViewerSelectionState;
+  clearSelectionState(): PrefViewerSelectionState;
+  getSelectionState(): PrefViewerSelectionState;
+  notifyElementClick(
+    element: PrefViewerElementDescriptor | PrefViewerElementDescriptor[] | { ids: PrefViewerElementDescriptor[] },
+  ): void;
+  appendSvgNode(id: string, svgId: string, svg: SVGElement): boolean;
+  removeAppendedSvgNodes(): void;
+
+  // ── Turnable (auto-rotate) state ──
+  startTurnable(options?: PrefViewerTurnableOptions): PrefViewerTurnableState;
+  stopTurnable(): PrefViewerTurnableState;
+  toggleTurnable(options?: PrefViewerTurnableOptions): PrefViewerTurnableState;
+  getTurnableState(): PrefViewerTurnableState;
+
+  // ── Dialog ──
+  openDialog(title: string, content: string | Node, footer?: string | Node): void;
+  closeDialog(): void;
+
+  // ── Animations (3D only) ──
+  // `getAnimations()` is deliberately absent here: the component shadows the standard
+  // `Element.getAnimations()` with an incompatible return, and TypeScript cannot model an
+  // incompatible override without making PrefViewer unassignable to HTMLElement. Read it
+  // through PrefViewerAnimationsApi instead. Renaming the runtime method would fix this
+  // properly, but that is a breaking change for the component's API (TEC-3490).
+  /** False when no animation of that name exists. */
+  playAnimation(name: string, action: PrefViewerAnimationAction): boolean;
+  setAnimationProgress(name: string, progress: number): boolean;
+  setAnimationLoop(name: string, loop: boolean): boolean;
+
+  // ── Downloads ──
+  downloadModelGLB(): void;
+  downloadModelGLTF(): void;
+  downloadModelUSDZ(): void;
+  downloadSceneGLB(): void;
+  downloadSceneGLTF(): void;
+  downloadSceneUSDZ(): void;
+  downloadModelAndSceneGLB(): void;
+  downloadModelAndSceneGLTF(): void;
+  downloadModelAndSceneUSDZ(): void;
+
+  addEventListener<K extends keyof PrefViewerEventMap>(
+    type: K,
+    listener: (this: PrefViewer, ev: PrefViewerEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  removeEventListener<K extends keyof PrefViewerEventMap>(
+    type: K,
+    listener: (this: PrefViewer, ev: PrefViewerEventMap[K]) => unknown,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void;
+}
+
+/**
+ * The observed attributes. Structured payloads (`config`, `model`, `scene`,
+ * `materials`, `drawing`, `options`, `styles`) are JSON strings when written as attributes —
+ * pass the objects through the matching method or property instead.
+ */
+export interface PrefViewerAttributes {
+  config?: string;
+  culture?: string;
+  drawing?: string;
+  materials?: string;
+  mode?: PrefViewerMode;
+  model?: string;
+  scene?: string;
+  options?: string;
+  styles?: string;
+  "show-model"?: boolean | "true" | "false";
+  "show-scene"?: boolean | "true" | "false";
+  "show-render-menu"?: boolean | "true" | "false";
 }
 
+/** <pref-viewer mode="3d" style="display:block; width:100%; height:600px" /> */
+type PrefViewerJsxProps = React.DetailedHTMLProps<
+  React.HTMLAttributes<PrefViewer> & PrefViewerAttributes,
+  PrefViewer
+>;
+
 declare global {
+  interface HTMLElementTagNameMap {
+    "pref-viewer": PrefViewer;
+  }
+
+  // React <= 18 (@types/react 18) resolves intrinsics through the global JSX namespace.
+  namespace JSX {
+    interface IntrinsicElements {
+      "pref-viewer": PrefViewerJsxProps;
+    }
+  }
+}
+
+// React 19 (@types/react 19) dropped the global JSX namespace: intrinsics resolve through
+// React.JSX instead. Declaring only the global one above leaves the element unknown on any
+// modern setup, which is why `<pref-viewer mode="3d" />` failed to compile (TEC-3490).
+declare module "react" {
   namespace JSX {
     interface IntrinsicElements {
-      /**
-       * <pref-viewer model="…" />
-       */
-      "pref-viewer": React.DetailedHTMLProps<
-        React.HTMLAttributes<HTMLElement> & { model?: string },
-        HTMLElement
-      >;
+      "pref-viewer": PrefViewerJsxProps;
     }
   }
 }
 
-export {};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@preference-sl/pref-viewer",
-    "version": "2.16.0-beta.14",
+    "version": "2.16.0-beta.18",
     "description": "Web Component to preview GLTF models with Babylon.js",
     "author": "Alex Moreno Palacio <amoreno@preference.es>",
     "scripts": {
@@ -25,6 +25,7 @@
     "types": "index.d.ts",
     "exports": {
         ".": {
+            "types": "./index.d.ts",
             "import": "./src/index.js",
             "require": "./src/index.js"
         }

package/src/babylonjs-controller.js

@@ -192,6 +192,11 @@ export default class BabylonJSController {
         resize: {
             throttleMs: 50, // Cap resize work to ~20 Hz while dragging/resizing containers
         },
+        defaultCameraFraming: {
+            margin: 1.25,          // Breathing room so the model doesn't touch the viewport edges
+            minRadiusFactor: 0.25, // Zoom in on detail
+            maxRadiusFactor: 4,    // Pull back past the whole model
+        },
         // Hardware-adaptive quality settings (applied based on GPU capabilities)
         quality: {
             // Settings for different hardware tiers: 'low', 'medium', 'high'
@@ -213,6 +218,24 @@ export default class BabylonJSController {
                 hemiLightIntensity: 0.52,
                 dirLightIntensity: 0.56,
                 cameraLightIntensity: 0.16,
+                // Daylight background, in the LINEAR domain the tonemapper consumes — NOT sRGB.
+                //
+                // The clear colour goes through the same exposure + ACES + gamma chain as the
+                // render, so the value that reads correctly here is not the value that reaches the
+                // screen. The previous literal was an sRGB 0.98 ("almost white") and it arrived as
+                // #C0C0C0, a mid grey.
+                //
+                // This one is solved against the ACES fit at exposure 0.92 and verified on screen:
+                // a light studio grey, #D9D9D9. Other targets, if this needs revisiting —
+                //   #F4F3F0 warm off-white (matches the host app's 2D/PR surface) -> 4.289 3.991 3.304
+                //   #D9D9D9 light studio                                (current) -> 1.424
+                //   #CCCCCC neutral studio                                        -> 1.112
+                //   #B3B3B3 darker                                                -> 0.688
+                // Note how steeply the required input climbs near white: that is the ACES shoulder,
+                // and it is why a near-white background needs a value well above 1.
+                //
+                // Re-solve these if exposure, contrast or the tonemapping curve change.
+                backgroundDay: [1.424, 1.424, 1.424],
             },
         },
     };
@@ -1637,7 +1660,8 @@ export default class BabylonJSController {
         const showroom = this.#config.look?.showroom || {};
         const imageProcessing = this.#scene.imageProcessingConfiguration;
 
-        this.#scene.clearColor = new Color4(0.98, 0.98, 0.98, 1).toLinearSpace();
+        const bg = showroom.backgroundDay ?? this.#config.look.showroom.backgroundDay;
+        this.#scene.clearColor = new Color4(bg[0], bg[1], bg[2], 1);
         imageProcessing.exposure = showroom.exposure ?? 0.95;
         imageProcessing.contrast = showroom.contrast ?? 1.08;
         imageProcessing.toneMappingEnabled = showroom.toneMappingEnabled ?? true;
@@ -1677,12 +1701,15 @@ export default class BabylonJSController {
             imageProcessing.colorCurvesEnabled = false;
         }
 
+        // Night end stays in low linear values (a dark blue sky); the day end is the calibrated
+        // HDR off-white. Both are linear already, so no toLinearSpace() on either.
+        const bgDay = showroom.backgroundDay ?? this.#config.look.showroom.backgroundDay;
         this.#scene.clearColor = new Color4(
-            lerp(0.035, 0.98, daylight),
-            lerp(0.045, 0.98, daylight),
-            lerp(0.085, 0.98, daylight),
+            lerp(0.000627, bgDay[0], daylight),
+            lerp(0.001089, bgDay[1], daylight),
+            lerp(0.004413, bgDay[2], daylight),
             1,
-        ).toLinearSpace();
+        );
 
         if ("environmentIntensity" in this.#scene) {
             this.#scene.environmentIntensity = lerp(0.42, showroom.environmentIntensity ?? 1.08, peakLight);
@@ -1754,6 +1781,78 @@ export default class BabylonJSController {
         this.#engine.setHardwareScalingLevel(scalingLevel);
     }
 
+    /**
+     * World-space bounds of the loaded model's renderable geometry.
+     * @private
+     * @returns {{center: Vector3, radius: number}|null} Centre and bounding-sphere radius, or null when nothing renderable is loaded.
+     */
+    #getModelBounds() {
+        const meshes = (this.#containers?.model?.assetContainer?.meshes ?? []).filter((mesh) => (mesh?.getTotalVertices?.() ?? 0) > 0);
+        if (meshes.length === 0) {
+            return null;
+        }
+
+        let min = null;
+        let max = null;
+        meshes.forEach((mesh) => {
+            mesh.computeWorldMatrix(true);
+            const box = mesh.getBoundingInfo?.()?.boundingBox;
+            if (!box) {
+                return;
+            }
+            min = min ? Vector3.Minimize(min, box.minimumWorld) : box.minimumWorld.clone();
+            max = max ? Vector3.Maximize(max, box.maximumWorld) : box.maximumWorld.clone();
+        });
+
+        if (!min || !max) {
+            return null;
+        }
+
+        const radius = Vector3.Distance(min, max) / 2;
+        if (!Number.isFinite(radius) || radius <= 0) {
+            return null;
+        }
+
+        return { center: Vector3.Center(min, max), radius };
+    }
+
+    /**
+     * Frames the default camera on the loaded model: aims it at the model's centre and pulls it
+     * back far enough for the whole model to fit the viewport.
+     *
+     * Only ever applied to the viewer's own camera — a camera authored in the model or the scene
+     * is a composition choice and is left untouched. Orbit angles are preserved so a model reload
+     * (an option or dimension change) re-centres without snapping the user's viewpoint back.
+     * @private
+     * @param {Camera|null|undefined} camera - The camera about to become active.
+     * @returns {void}
+     */
+    #fitDefaultCameraToModel(camera) {
+        if (camera !== this.#camera || !(camera instanceof ArcRotateCamera)) {
+            return;
+        }
+
+        const bounds = this.#getModelBounds();
+        if (!bounds) {
+            return;
+        }
+
+        // fovMode is FOVMODE_HORIZONTAL_FIXED (see #applyShowroomCameraFraming), so camera.fov is
+        // the horizontal angle and the vertical one follows the aspect ratio. Fitting to the
+        // horizontal angle alone clips the model top and bottom on any viewport wider than tall.
+        const aspect = this.#engine?.getAspectRatio?.(camera) || 1;
+        const horizontalFov = camera.fov;
+        const verticalFov = 2 * Math.atan(Math.tan(horizontalFov / 2) / aspect);
+        const limitingFov = Math.min(horizontalFov, verticalFov);
+        const distance = (bounds.radius / Math.sin(limitingFov / 2)) * this.#config.defaultCameraFraming.margin;
+
+        camera.setTarget(bounds.center);
+        camera.radius = distance;
+        // The 5-20 m defaults were sized for a room; left in place they clamp the fit itself.
+        camera.lowerRadiusLimit = distance * this.#config.defaultCameraFraming.minRadiusFactor;
+        camera.upperRadiusLimit = distance * this.#config.defaultCameraFraming.maxRadiusFactor;
+    }
+
     /**
      * Keeps the showroom camera framing stable when the viewport aspect ratio changes.
      * The 3D showroom is meant to feel compositionally stable, so we prefer a horizontal-fixed
@@ -2328,6 +2427,7 @@ export default class BabylonJSController {
             }
         }
         this.#applyShowroomCameraFraming(camera);
+        this.#fitDefaultCameraToModel(camera);
         this.#scene.activeCamera?.detachControl();
         camera.detachControl();
         if (!cameraState.locked) {