three-cad-viewer 4.3.8 → 5.0.0

package/{README.md → Readme.md}

@@ -314,7 +314,7 @@ The keymap serves two purposes:
 - **Modifier keys** (`shift`, `ctrl`, `meta`, `alt`) remap which physical modifier key is used for mouse interactions (e.g. shift-click to isolate, ctrl-rotate). Values are DOM event properties like `"shiftKey"`, `"ctrlKey"`, `"metaKey"`, `"altKey"`.
 - **Action shortcuts** map single keys (with or without Shift) to toolbar buttons, camera presets, tab switches, and animation control. Only plain keys are supported — Ctrl/Alt/Meta combinations are reserved for modifier-based mouse interactions.
 
-Click on the viewer to give it focus, then press shortcut keys to trigger actions. Button tooltips show `[key]` suffixes when shortcuts are configured.
+Click on the viewer to give it focus, then press shortcut keys to trigger actions. Button and tab tooltips show a `› key` suffix when shortcuts are configured.
 
 The default keymap:
 
@@ -323,19 +323,19 @@ keymap: {
   // Modifier keys (remap physical keys for mouse interactions)
   shift: "shiftKey", ctrl: "ctrlKey", meta: "metaKey", alt: "altKey",
   // Toggle buttons
-  axes: "a", axes0: "A", grid: "g", gridxy: "G",
+  axes: "A", axes0: "0", grid: "g", gridxy: "G",
   perspective: "p", transparent: "t", blackedges: "b",
   explode: "x", zscale: "L",
-  distance: "D", properties: "P", select: "S",
+  distance: "D", properties: "P", select: "I",
   // Execute buttons
   reset: "R", resize: "r",
-  iso: "0", front: "1", rear: "2", top: "3", bottom: "4", left: "5", right: "6",
+  iso: "5", front: "1", rear: "3", top: "8", bottom: "2", left: "4", right: "6",
   // Help
   help: "h",
   // Animation
   play: " ", stop: "Escape",
   // Tab selection
-  tree: "T", clip: "C", material: "M", zebra: "Z",
+  tree: "T", clip: "C", material: "M", zebra: "Z", studio: "S",
 }
 ```
 
@@ -347,6 +347,8 @@ const displayOptions = {
 };
 ```
 
+**Topo filter shortcuts.** When the shape filter is visible (B-rep models), the lowercase keys `a` (All), `v` (Vertex), `e` (Edge), `f` (Face), `s` (Solid) set the picking filter. These are fixed (not part of the configurable keymap) — which is why `axes` and `studio` default to the uppercase `A`/`S`.
+
 ## Examples
 
 To understand the data format, a look at the simple 1 unit sized box might be helpful:

package/dist/core/picking-controller.d.ts

@@ -0,0 +1,125 @@
+import * as THREE from "three";
+import { type IdPicker } from "../rendering/id-picking.js";
+import { type PickedComponent } from "../rendering/picked.js";
+import type { Shapes } from "./types.js";
+import type { RenderedState } from "./viewer.js";
+import type { Display } from "../ui/display.js";
+import type { Tools } from "../tools/cad_tools/tools.js";
+/**
+ * The narrow surface {@link PickingController} needs from its host (the Viewer).
+ * Keeps the controller decoupled from the rest of the Viewer god-object and
+ * unit-testable. `rendered` is a lazy getter that throws before render() — the
+ * controller must always read through it (never cache `nestedGroup`/`highlight`,
+ * which are rebuilt every render()).
+ */
+export interface PickHost {
+    readonly idPicker: IdPicker | null;
+    readonly ready: boolean;
+    readonly hasAnimationLoop: boolean;
+    /** True while the Studio (presentation) tab owns the render. */
+    readonly studioActive: boolean;
+    readonly shapes: Shapes | null;
+    readonly renderer: THREE.WebGLRenderer;
+    readonly rendered: RenderedState;
+    readonly display: Display;
+    readonly cadTools: Tools;
+    update(updateMarker: boolean, notify: boolean): void;
+    /** Restore the most recently meta-double-click-hidden leaf (hide-undo stack). */
+    showLastHidden(): void;
+    handlePick(path: string, name: string, meta: boolean, shift: boolean, alt: boolean, point: THREE.Vector3 | null, nodeType?: string | null, tree?: boolean): void;
+}
+/**
+ * Owns all pointer-driven picking on the compact graph: hover preselection
+ * (highlight + status line), left-click selection commit, right-click/key removal,
+ * and double-click pick. Hover proposes the component under the cursor
+ * ({@link lastObject}); a left-click commits it ({@link lastSelection}) — one state
+ * machine, so both fields live here.
+ *
+ * Listener lifecycle: hover (pointermove/leave) is always-on and added at
+ * construction; selection (mousedown/mouseup + document keydown) is tool-scoped via
+ * {@link setSelectionInput}; double-click via {@link setPickHandler}. {@link dispose}
+ * tears them all down.
+ */
+export declare class PickingController {
+    private readonly host;
+    /** Component under the cursor (hover); committed on left-click. */
+    lastObject: PickedComponent | null;
+    /** Last committed selection. */
+    lastSelection: PickedComponent | null;
+    private idHoverClientX;
+    private idHoverClientY;
+    private idHoverInside;
+    private idHoverRenderQueued;
+    /** Per-component hover status text (fixed per mesh; cleared on reload / z-scale). */
+    private hoverStatusCache;
+    private selectionInputActive;
+    private selectDownPosition;
+    private pickHandlerActive;
+    constructor(host: PickHost);
+    /** Remove every listener this controller owns. */
+    dispose(): void;
+    /** Record the cursor position over the canvas. */
+    private onIdHoverMove;
+    /** Cursor left the canvas → clear any hover highlight. */
+    private onIdHoverLeave;
+    /**
+     * Whether hover preselection (highlight + status line) is active. Disabled for GDS:
+     * dense, stacked, instance-unrolled layout data where per-pixel hover flickers
+     * endlessly and the B-rep readout ("area ≈ …") is meaningless, so GDS is
+     * double-click-identify only. Also disabled in Studio (presentation) mode: hover
+     * tint/status is a CAD/analysis affordance, not wanted in Studio, and skipping it
+     * means the id buffer is never re-rendered for a bare mouse-move there.
+     */
+    private hoverPreselectActive;
+    /**
+     * Called once per render: drive hover preselection unless a model is GDS or the
+     * camera is being dragged.
+     */
+    handleHover(): void;
+    /**
+     * Hover via the GPU id picker on the compact graph: resolve the component under the
+     * cursor and drive the shader `HighlightController`. Sets {@link lastObject}
+     * (committed on left-click by {@link commitSelection} when a tool is active).
+     */
+    private handleIdHover;
+    /** Drop the cached hover texts (e.g. on z-scale change — world lengths change). */
+    invalidateHoverCache(): void;
+    /**
+     * Drop any lingering hover highlight + status line (keeping the committed selection).
+     * Called when entering Studio mode: hover preselection is disabled there, so the
+     * per-render {@link handleHover} no longer runs its own release and a stale tint/status
+     * from CAD mode would otherwise persist.
+     */
+    clearHover(): void;
+    /**
+     * Whether the component a pick resolved to is currently visible — used to drop picks
+     * of hidden geometry. Visibility is the owning group's material `visible` flag
+     * (faces for solids/standalone faces; edge/vertex materials for standalone leaves).
+     */
+    private pickVisible;
+    clearSelection: () => void;
+    private releaseLastSelected;
+    removeLastSelected(): void;
+    /** Drop selection state + hover cache + status line (on model reload). */
+    reset(): void;
+    /**
+     * Add/remove the canvas mousedown+mouseup and document keydown listeners
+     * (idempotent, guarded on `selectionInputActive`). Hover maintains
+     * {@link lastObject}; these handlers commit it on left-click and handle the key +
+     * right-click actions.
+     */
+    setSelectionInput(flag: boolean): void;
+    private onSelectMouseDown;
+    private onSelectMouseUp;
+    private onSelectKeyDown;
+    private commitSelection;
+    setPickHandler(flag: boolean): void;
+    /**
+     * Double-click pick via the GPU id picker: `idPicker.pickAt` resolves the component
+     * under the cursor, the registry gives its owning tree-leaf path ({@link leafPath}),
+     * and the readback world-space `point` feeds `handlePick` (the `shift && meta` camera
+     * target, with a bbox-center fallback when `point` is null). No topo filter: a
+     * double-click selects whatever is under the cursor and resolves it to its leaf.
+     */
+    private onDoubleClick;
+}

package/dist/core/studio-manager.d.ts

@@ -48,6 +48,13 @@ declare class StudioManager {
     private _savedClippingState;
     private _shadowLights;
     private _ctx;
+    /**
+     * Renderer pixel ratio saved on Studio entry, restored on leave.
+     * Studio mode bumps the pixel ratio to apply supersampling, which
+     * compensates for low DPR (e.g., VSCode webviews report DPR=1 even
+     * on Retina displays) and improves AA on shallow-angle edges.
+     */
+    private _savedPixelRatio;
     constructor(ctx: StudioManagerContext);
     get isActive(): boolean;
     get hasComposer(): boolean;

package/dist/core/types.d.ts

@@ -185,8 +185,12 @@ export interface DisplayOptions {
     zebraTool?: boolean;
     /** Show studio tool (default: true) */
     studioTool?: boolean;
-    /** Enable measurement debug mode (default: false) */
-    measurementDebug?: boolean;
+    /**
+     * Use an external (Python/`ocp_vscode`) measurement backend (default: false).
+     * When false, the built-in TypeScript mesh-based measurement backend answers
+     * measurements locally — so measure works without a backend connection.
+     */
+    externalMeasurementBackend?: boolean;
     /** External canvas element to use for the WebGL renderer, enabling shared WebGL context scenarios (default: undefined — renderer creates its own canvas) */
     canvas?: HTMLCanvasElement;
     /** External WebGL context to use for the renderer. When provided together with `canvas`, the renderer will use this context instead of creating a new one. Useful for sharing a context with other renderers like PixiJS. (default: undefined) */
@@ -271,6 +275,14 @@ export interface ViewerOptions extends StudioModeOptions {
     zoomSpeed?: number;
     /** Show timings in browser console (default: false) */
     timeit?: boolean;
+    /**
+     * Tab to land on after render (default: "tree", i.e. CAD mode).
+     * When set to a non-tree tab, the initial CAD paint is skipped so the
+     * user doesn't see a brief CAD-mode flicker before the target tab takes
+     * over. Especially noticeable for "studio" (async env-map load) and
+     * "zebra" (material swap).
+     */
+    tab?: ActiveTab;
 }
 /** Zebra tool options */
 export interface ZebraOptions {
@@ -330,7 +342,7 @@ export interface ViewerStateShape {
     zscaleTool: boolean;
     zebraTool: boolean;
     studioTool: boolean;
-    measurementDebug: boolean;
+    externalMeasurementBackend: boolean;
     ambientIntensity: number;
     directIntensity: number;
     metalness: number;
@@ -493,9 +505,12 @@ export interface MaterialAppearance {
  *
  * This format is produced by the threejs-materials Python library, which catalogs
  * PBR materials from ambientCG, GPUOpen, PolyHaven, and PhysicallyBased.
- * `values` contains scalar properties (e.g., color as linear RGB array,
- * roughness as float).  `textures` contains texture references (inline data URIs
- * or file paths) keyed by property name.
+ * `values` contains scalar properties (e.g., color as an sRGB RGB array,
+ * roughness as float).  Note the per-key color-space convention: `color` is
+ * sRGB-stored, while `emissive`/`specularColor`/`sheenColor`/`attenuationColor`
+ * are linear-stored (see MaterialFactory.createStudioMaterialFromMaterialX).
+ * `textures` contains texture references (inline data URIs or file paths)
+ * keyed by property name.
  *
  * Detected by the presence of the `values` key.
  * Extra keys from threejs-materials (id, name, source, url, license) pass through
@@ -508,6 +523,9 @@ export interface MaterialXMaterial {
     textures: Record<string, string>;
     /** Optional texture tiling [u, v], default [1, 1]. Applied to all textures. */
     textureRepeat?: [number, number];
+    /** Optional texture rotation in **radians**, counterclockwise. Pivot is
+     *  the texture center (0.5, 0.5). Applied to all textures. */
+    textureRotation?: number;
 }
 /**
  * Type guard to check if a material entry is a threejs-materials format dict.

package/dist/core/viewer-state.d.ts

@@ -20,7 +20,7 @@ interface DisplayDefaults {
     zscaleTool: boolean;
     zebraTool: boolean;
     studioTool: boolean;
-    measurementDebug: boolean;
+    externalMeasurementBackend: boolean;
 }
 /**
  * Render configuration defaults

package/dist/core/viewer.d.ts

@@ -19,7 +19,10 @@ import { Controls } from "../camera/controls.js";
 import { Camera, type CameraDirection } from "../camera/camera.js";
 import { BoundingBox, BoxHelper } from "../scene/bbox.js";
 import { Tools } from "../tools/cad_tools/tools.js";
-import { PickedObject, Raycaster } from "../rendering/raycast.js";
+import { MeshMeasureBackend } from "../tools/cad_tools/mesh-measure.js";
+import { IdPicker } from "../rendering/id-picking.js";
+import { type PickedComponent } from "../rendering/picked.js";
+import { PickingController } from "./picking-controller.js";
 import { ViewerState } from "./viewer-state.js";
 import type { Display } from "../ui/display.js";
 import type { Vector3Tuple, QuaternionTuple } from "three";
@@ -70,14 +73,6 @@ interface ImageResult {
     task: string;
     dataUrl: string | ArrayBuffer | null;
 }
-/**
- * Raycast event from keyboard or mouse.
- */
-interface RaycastEvent {
-    key?: string;
-    mouse?: "left" | "right";
-    shift?: boolean;
-}
 /**
  * Backend response structure.
  */
@@ -90,7 +85,7 @@ interface BackendResponse {
  */
 interface DisplayOptionsInternal {
     measureTools?: boolean;
-    measurementDebug?: boolean;
+    externalMeasurementBackend?: boolean;
     selectTool?: boolean;
     explodeTool?: boolean;
     zscaleTool?: boolean;
@@ -106,7 +101,7 @@ interface DisplayOptionsInternal {
  * State that exists only after render() and before clear().
  * Groups all resources that are created together during rendering.
  */
-interface RenderedState {
+export interface RenderedState {
     scene: THREE.Scene;
     ambientLight: THREE.AmbientLight;
     directLight: THREE.DirectionalLight;
@@ -167,6 +162,12 @@ declare class Viewer {
     onAfterRender: (() => void) | null;
     mouse: THREE.Vector2;
     cadTools: Tools;
+    /**
+     * Internal mesh-based measurement backend, used when
+     * `externalMeasurementBackend === false` (the default). Resolves component paths
+     * against the compact group's {@link MeshGeometrySource}.
+     */
+    meshBackend: MeshMeasureBackend;
     animation: Animation;
     clipNormals: [THREE.Vector3, THREE.Vector3, THREE.Vector3];
     private _rendered;
@@ -193,19 +194,24 @@ declare class Viewer {
     renderOptions: RenderOptions | null;
     lastNotification: Record<string, unknown>;
     lastBbox: LastBboxInfo | null;
-    lastObject: PickedObject | null;
-    lastSelection: PickedObject | null;
+    private _hiddenUndo;
     lastPosition: THREE.Vector3 | null;
     bboxNeedsUpdate: boolean;
     keepHighlight: boolean;
-    expandedTree: ShapeTreeData | null;
     compactTree: ShapeTreeData | null;
-    expandedNestedGroup: NestedGroup | null;
     compactNestedGroup: NestedGroup | null;
-    raycaster: Raycaster | null;
+    private _lastPickCam;
+    private _lastPickProj;
+    private _lastClipSig;
+    private _suppressUpdate;
+    private _zebraSettingsApplied;
+    idPicker: IdPicker | null;
+    pickingController: PickingController;
     private _studioManager;
     /** Environment manager — proxied from StudioManager for display.ts access. */
     get envManager(): import("../index.js").EnvironmentManager;
+    /** True while the Studio (presentation) tab owns the render. PickHost member. */
+    get studioActive(): boolean;
     zScale: number;
     clipNormal0: Vector3Tuple | null;
     clipNormal1: Vector3Tuple | null;
@@ -250,11 +256,10 @@ declare class Viewer {
     private getShapeRenderer;
     /**
      * Render the shapes of the CAD object.
-     * @param exploded - Whether to render the compact or exploded version
      * @param shapes - The Shapes object.
      * @returns A nested THREE.Group object and navigation tree.
      */
-    renderTessellatedShapes(exploded: boolean, shapes: Shapes): RenderResult;
+    renderTessellatedShapes(shapes: Shapes): RenderResult;
     /**
      * Add a position animation track (full 3D translation).
      * @param selector - path/id of group to be animated.
@@ -341,7 +346,7 @@ declare class Viewer {
      * - WebGL renderer and context
      * - All Three.js objects (geometries, materials, textures)
      * - Event listeners
-     * - CAD tools and raycaster
+     * - CAD tools and id picker
      *
      * After calling dispose(), the viewer instance should not be used.
      *
@@ -357,15 +362,6 @@ declare class Viewer {
      * @public
      */
     clear(): void;
-    /**
-     * Synchronizes the states of two tree structures recursively.
-     *
-     * @param compactTree - The compact tree structure.
-     * @param expandedTree - The expanded tree structure.
-     * @param exploded - Whether rendering in exploded mode.
-     * @param path - The current path in the tree structure.
-     */
-    syncTreeStates: (compactTree: ShapeTreeData | VisibilityState, expandedTree: ShapeTreeData | VisibilityState, exploded: boolean, path: string) => void;
     /**
      * Get the color of a node from its path
      * @param path - path of the CAD object
@@ -374,16 +370,9 @@ declare class Viewer {
     /**
      * Build nestedGroup and treeview for initial render.
      * @param scene - The scene to add the group to
-     * @param expanded - whether to render the exploded or compact version
      * @returns The nestedGroup and treeview
      */
     private buildInitialGroup;
-    /**
-     * Toggle the two version of the NestedGroup.
-     * Must only be called after render() has completed.
-     * @param expanded - whether to render the exploded or compact version
-     */
-    toggleGroup(expanded: boolean): void;
     /**
      * Set the active sidebar tab.
      * @param tabName - Tab name: "tree", "clip", "material", "zebra", or "studio"
@@ -533,22 +522,30 @@ declare class Viewer {
      * @param tree - whether from tree
      */
     handlePick: (path: string, name: string, meta: boolean, shift: boolean, alt: boolean, point: THREE.Vector3 | null, nodeType?: string | null, tree?: boolean) => void;
-    setPickHandler(flag: boolean): void;
     /**
-     * Find the shape that was double clicked and send notification
-     * @param e - a DOM PointerEvent or MouseEvent
+     * Record a leaf about to be hidden via meta-double-click onto the hide-undo stack,
+     * capturing its current (pre-hide) visibility state for a faithful restore. Dedups:
+     * an existing entry for the same id is dropped so the id moves to the top.
      */
-    pick: (e: PointerEvent | MouseEvent) => void;
-    clearSelection: () => void;
-    _releaseLastSelected: () => void;
-    _removeLastSelected: () => void;
+    private _recordHidden;
     /**
-     * Set raycast mode
-     * @param flag - turn raycast mode on or off
+     * Restore the most recently meta-double-click-hidden leaf (LIFO), skipping entries
+     * that no longer apply — removed objects, or ones already shown again via the tree.
+     * In Studio the restored leaf keeps edges off (presentation); in CAD its pre-hide
+     * edge state is restored. Bound to a meta-double-click on empty space, so a hidden
+     * object can be brought back without the tree (notably in Studio). @public
      */
-    setRaycastMode(flag: boolean): void;
-    handleRaycast: () => void;
-    handleRaycastEvent: (event: RaycastEvent) => void;
+    showLastHidden: () => void;
+    /** Component under the cursor (hover); committed on left-click. */
+    get lastObject(): PickedComponent | null;
+    /** Last committed selection. */
+    get lastSelection(): PickedComponent | null;
+    /** Enable/disable the double-click pick handler (on when no tool is active). */
+    setPickHandler(flag: boolean): void;
+    /** Enable/disable click+key selection input (on while a select/measure tool is active). */
+    setSelectionInput(flag: boolean): void;
+    /** Clear the current selection (and reset the select tool). */
+    clearSelection: () => void;
     /**
      * Handle a backend response sent by the backend
      * The response is a JSON object sent by the Python backend through VSCode

package/dist/index.d.ts

@@ -15,10 +15,10 @@ import { Timer } from "./utils/timer.js";
 import { logger } from "./utils/logger.js";
 import { gpuTracker } from "./utils/gpu-tracker.js";
 import { version } from "./_version.js";
-export { Viewer, Display, EnvironmentManager, Timer, logger, gpuTracker, version };
-export { MATERIAL_PRESETS, MATERIAL_PRESET_NAMES } from "./rendering/material-presets.js";
+export { Viewer, Display, EnvironmentManager, Timer, logger, gpuTracker, version, };
+export { MATERIAL_PRESETS, MATERIAL_PRESET_NAMES, } from "./rendering/material-presets.js";
 export type { LogLevel } from "./utils/logger.js";
-export type { ResourceType, TrackedResource, ResourceSummary } from "./utils/gpu-tracker.js";
+export type { ResourceType, TrackedResource, ResourceSummary, } from "./utils/gpu-tracker.js";
 export type { Vector3Tuple, QuaternionTuple } from "three";
 export type { ThemeInput, Theme, ControlType, UpDirection, AnimationMode, ActiveTab, ZebraColorScheme, ZebraMappingMode, ShapeType, ShapeSubtype, Axis, ClipIndex, ColorValue, RGBColor, RGBAColor, AxisColors, AxisColorsFlatArray, } from "./core/types.js";
 export { CLIP_INDICES, isClipIndex, CollapseState } from "./core/types.js";
@@ -27,12 +27,12 @@ export type { BoundingBox, BoundingSphere, BoundingBoxFlat, } from "./core/types
 export type { PickInfo } from "./core/types.js";
 export type { ChangeInfos, ChangeNotification, NotificationCallback, } from "./core/types.js";
 export type { DisplayOptions, RenderOptions, ViewerOptions, ZebraOptions, CombinedOptions, } from "./core/types.js";
-export type { ViewerStateShape, StateKey, } from "./core/types.js";
+export type { ViewerStateShape, StateKey } from "./core/types.js";
 export type { Texture, Shape, ShapeBinary, ShapeNested, Location, VisibilityValue, VisibilityState, Shapes, } from "./core/types.js";
 export { isShapeBinaryFormat, hasTrianglesPerFace, hasSegmentsPerEdge, } from "./core/types.js";
 export type { DomEventCallback } from "./core/types.js";
 export type { ColoredMaterial } from "./core/types.js";
 export type { MaterialAppearance, MaterialXMaterial, StudioOptions, StudioBackground, StudioModeOptions, StudioEnvironment, StudioToneMapping, StudioTextureMapping, } from "./core/types.js";
 export { isMaterialXMaterial } from "./core/types.js";
-export { isInstancedFormat, decodeInstancedFormat } from "./utils/decode-instances.js";
+export { isInstancedFormat, decodeInstancedFormat, } from "./utils/decode-instances.js";
 export type { SubscribeOptions } from "./core/types.js";

package/dist/rendering/environment.d.ts

@@ -31,14 +31,6 @@ interface EnvironmentManagerOptions {
 declare class EnvironmentManager {
     /** Cached PMREM render targets keyed by environment name or URL */
     private _cache;
-    /**
-     * Cached raw equirectangular HDR textures keyed by the same name/URL.
-     * Preserved (not disposed after PMREM generation) so `scene.background`
-     * can sample the original HDR at full source resolution instead of the
-     * 256² PMREM cubemap. Only populated by `_loadHdr` — procedural
-     * environments have no source HDR.
-     */
-    private _hdrCache;
     /** Cached light detection results keyed by environment name or URL */
     private _lightDetectionCache;
     /** In-flight load promises keyed by environment name or URL */
@@ -55,13 +47,6 @@ declare class EnvironmentManager {
     private _hdrLoader;
     /** The last loaded PMREM texture (stateful — used by apply() for IBL) */
     private _currentTexture;
-    /**
-     * Raw HDR texture corresponding to `_currentTexture`, used for
-     * `scene.background` to keep the backdrop at source resolution. Null when
-     * the current environment is procedural ("studio" RoomEnvironment) — in
-     * that case the background falls back to `_currentTexture` (the PMREM).
-     */
-    private _currentBackgroundTexture;
     /** Whether this manager has been disposed */
     private _disposed;
     /**
@@ -236,10 +221,9 @@ declare class EnvironmentManager {
      * Load an HDR file and generate a PMREM texture from it.
      *
      * Uses HDRLoader to fetch the .hdr file, then PMREMGenerator.fromEquirectangular()
-     * to create the PMREM cubemap for IBL. The source equirectangular HDR is
-     * preserved and cached separately (in `_hdrCache`) so that "environment"
-     * background mode can sample the full-resolution equirectangular texture
-     * instead of the 256² PMREM cubemap.
+     * to create the PMREM cubemap. The source equirectangular HDR is disposed
+     * after PMREM generation. The PMREM texture itself serves as both the IBL
+     * environment and the background (in "environment" mode).
      *
      * @param url - URL of the .hdr file
      * @param cacheKey - Cache key for the resulting PMREM render target