@idetik/core 0.40.0 → 0.40.1

package/dist/index.js

@@ -1079,30 +1079,53 @@ function TI(g, A) {
   };
 })();
 class SA {
+  /** Minimum corner of the box. */
   min;
+  /** Maximum corner of the box. */
   max;
   /**
-   * Initializes as an empty box if no values are provided using the
-   * "empty-by-sentinel" pattern: min = +Infinity, max = -Infinity.
-   * This allows expansion functions to work without special-casing
-   * the first element, and avoids biasing toward (0,0,0).
+   * Creates a box from optional corner points. The corners are cloned.
+   * When a corner is omitted the box starts empty.
+   *
+   * @param min - The minimum corner.
+   * @param max - The maximum corner.
    */
   constructor(A, I) {
     this.min = A ? EA(A) : p(1 / 0, 1 / 0, 1 / 0), this.max = I ? EA(I) : p(-1 / 0, -1 / 0, -1 / 0);
   }
+  /** Returns a deep copy of the box. */
   clone() {
     return new SA(this.min, this.max);
   }
+  /** Returns `true` when the box encloses no volume. */
   isEmpty() {
     return this.max[0] <= this.min[0] || this.max[1] <= this.min[1] || this.max[2] <= this.min[2];
   }
-  // Half-open interval intersection: returns true only if boxes overlap.
+  /**
+   * Tests whether two boxes overlap. Boxes are treated as half-open
+   * intervals so touching faces do not count as overlap.
+   *
+   * @param a - The first box.
+   * @param b - The second box.
+   */
   static intersects(A, I) {
     return !(A.max[0] <= I.min[0] || A.min[0] >= I.max[0] || A.max[1] <= I.min[1] || A.min[1] >= I.max[1] || A.max[2] <= I.min[2] || A.min[2] >= I.max[2]);
   }
+  /**
+   * Grows the box in place to contain the given point.
+   *
+   * @param p - The point to include.
+   */
   expandWithPoint(A) {
     A[0] < this.min[0] && (this.min[0] = A[0]), A[1] < this.min[1] && (this.min[1] = A[1]), A[2] < this.min[2] && (this.min[2] = A[2]), A[0] > this.max[0] && (this.max[0] = A[0]), A[1] > this.max[1] && (this.max[1] = A[1]), A[2] > this.max[2] && (this.max[2] = A[2]);
   }
+  /**
+   * Transforms the box in place by the given matrix. The result is the
+   * axis-aligned box of the eight transformed corners so the box can grow
+   * under rotation.
+   *
+   * @param matrix - The transform to apply.
+   */
   applyTransform(A) {
     const { min: I, max: B } = this, C = [
       p(I[0], I[1], I[2]),
@@ -1611,36 +1634,55 @@ class wQ {
   }
 }
 class AA {
+  /** Minimum corner of the box. */
   min;
+  /** Maximum corner of the box. */
   max;
   /**
-   * Initializes as an empty box if no values are provided using the
-   * "empty-by-sentinel" pattern: min = +Infinity, max = -Infinity.
-   * This allows expansion functions to work without special-casing
-   * the first element, and avoids biasing toward (0,0).
+   * Creates a box from optional corner points. The corners are cloned.
+   * When a corner is omitted the box starts empty.
+   *
+   * @param min - The minimum corner.
+   * @param max - The maximum corner.
    */
   constructor(A, I) {
     this.min = A ? zg(A) : V(1 / 0, 1 / 0), this.max = I ? zg(I) : V(-1 / 0, -1 / 0);
   }
+  /** Returns a deep copy of the box. */
   clone() {
     return new AA(this.min, this.max);
   }
+  /** Returns `true` when the box encloses no area. */
   isEmpty() {
     return this.max[0] <= this.min[0] || this.max[1] <= this.min[1];
   }
-  // Half-open interval intersection: returns true only if boxes overlap.
+  /**
+   * Tests whether two boxes overlap. Boxes are treated as half-open
+   * intervals so touching edges do not count as overlap.
+   *
+   * @param a - The first box.
+   * @param b - The second box.
+   */
   static intersects(A, I) {
     return !(A.max[0] <= I.min[0] || A.min[0] >= I.max[0] || A.max[1] <= I.min[1] || A.min[1] >= I.max[1]);
   }
+  /**
+   * Tests whether two boxes have exactly equal corners.
+   *
+   * @param a - The first box.
+   * @param b - The second box.
+   */
   static equals(A, I) {
     return _g(A.min, I.min) && _g(A.max, I.max);
   }
+  /** Returns a copy with both corners floored componentwise. */
   floor() {
     return new AA(
       V(Math.floor(this.min[0]), Math.floor(this.min[1])),
       V(Math.floor(this.max[0]), Math.floor(this.max[1]))
     );
   }
+  /** Converts the box to an `x, y, width, height` rectangle. */
   toRect() {
     const A = this.min[0], I = this.min[1], B = this.max[0] - this.min[0], C = this.max[1] - this.min[1];
     return { x: A, y: I, width: B, height: C };
@@ -2975,16 +3017,22 @@ class mQ {
   }
 }
 class uQ {
+  /** The viewport's unique identifier. */
   id;
+  /** The host element defining the viewport's area. */
   element;
+  /** The camera the viewport renders with. */
   camera;
+  /** The pointer and wheel event dispatcher for the host element. */
   events;
+  /** Input controls driving the camera. */
   cameraControls;
   // Carried only to relay to `layer.onAttached` / `layer.onDetached`.
   // To be removed when the chunk-infrastructure refactor folds chunk management
   // into the source and the attach lifecycle goes away.
   context_;
   layers_ = [];
+  /** @hidden */
   constructor(A) {
     this.id = A.id, this.element = A.element, this.camera = A.camera, this.context_ = A.context, this.cameraControls = A.cameraControls, this.updateAspectRatio(), this.events = new fQ(this.element), this.events.addEventListener((I) => {
       if (I.event instanceof PointerEvent || I.event instanceof WheelEvent) {
@@ -3000,26 +3048,51 @@ class uQ {
     for (const I of A.layers ?? [])
       this.addLayer(I);
   }
+  /**
+   * The layers rendered by this viewport in order. Layers with `occludes`
+   * set draw before non-occluding layers regardless of stack order.
+   */
   get layers() {
     return this.layers_;
   }
+  /**
+   * Adds a layer to the top of the stack.
+   *
+   * @param layer - The layer to add.
+   */
   addLayer(A) {
     A.onAttached(this.context_), this.layers_.push(A);
   }
+  /**
+   * Removes a previously added layer.
+   *
+   * @param layer - The layer to remove.
+   */
   removeLayer(A) {
     const I = this.layers_.indexOf(A);
     if (I === -1)
       throw new Error(`Layer to remove not found: ${A}`);
     this.layers_.splice(I, 1), A.onDetached(this.context_);
   }
+  /** Removes all layers from the viewport. */
   removeAllLayers() {
     for (const A of this.layers_)
       A.onDetached(this.context_);
     this.layers_ = [];
   }
+  /**
+   * Syncs the camera's aspect ratio to the host element's size. Called
+   * automatically when the host element resizes.
+   */
   updateSize() {
     this.updateAspectRatio();
   }
+  /**
+   * Computes the viewport's box relative to the given canvas in device pixels.
+   *
+   * @param canvas - The canvas to compute the box against.
+   * @returns The viewport's box in the canvas's coordinate space.
+   */
   getBoxRelativeTo(A) {
     const I = this.getBox().toRect(), B = A.getBoundingClientRect(), C = window.devicePixelRatio || 1, Q = B.left * C, E = B.top * C, i = B.height * C, o = I.x - Q, a = I.y - E, s = Math.floor(o), D = Math.floor(i - a - I.height), h = Math.floor(I.width), t = Math.floor(I.height);
     return new AA(
@@ -3027,9 +3100,19 @@ class uQ {
       V(s + h, D + t)
     );
   }
+  /**
+   * The viewport's rectangle in the drawing buffer in device pixels.
+   */
   getBufferRect() {
     return this.getBoxRelativeTo(this.element).toRect();
   }
+  /**
+   * Converts a client-space position to clip space. The `y` axis points
+   * down, matching the renderer's mirrored projection.
+   *
+   * @param position - The client-space position to convert.
+   * @param depth - The clip-space z value.
+   */
   clientToClip(A, I = 0) {
     const [B, C] = A, Q = this.element.getBoundingClientRect();
     return p(
@@ -3038,6 +3121,13 @@ class uQ {
       I
     );
   }
+  /**
+   * Converts a client-space position such as a pointer location to world
+   * space.
+   *
+   * @param position - The client-space position to convert.
+   * @param depth - The clip-space z value.
+   */
   clientToWorld(A, I = 0) {
     const B = this.clientToClip(A, I);
     return this.camera.clipToWorld(B);
@@ -3153,63 +3243,22 @@ class xQ {
 }
 const WQ = 2048;
 class no {
+  /** The canvas element the renderer draws into. */
+  canvas;
+  /** The registered overlays that update once per frame in order. */
+  overlays;
   chunkManager_;
   context_;
   renderer_;
   viewports_;
-  canvas;
-  overlays;
   stats_;
   sizeObserver_;
   lastAnimationId_;
-  // this value will be set after start
   lastTimestamp_ = 0;
   /**
-   * Creates a new Idetik visualization runtime instance.
-   *
-   * @param params - Configuration parameters for the Idetik instance
-   * @param params.canvas - HTMLCanvasElement to render to
-   * @param params.viewports - Optional array of viewport configurations.
-   *   Each viewport renders with its own camera, layers, and controls.
-   *   The `element` property is optional and defaults to the canvas if not provided.
-   *   Elements must be unique across viewports.
-   *   The `id` property is optional but useful for referencing specific viewports later.
-   * @param params.overlays - Optional array of overlay objects that update each frame (e.g., for HUD elements)
-   * @param params.showStats - Optional flag to display performance statistics
-   *
-   * @example
-   * // Single viewport (element defaults to canvas)
-   * const camera = new OrthographicCamera({ left: 0, right: 1024, top: 0, bottom: 1024 });
-   * const idetik = new Idetik({
-   *   canvas: document.querySelector('canvas')!,
-   *   viewports: [{
-   *     camera: camera,
-   *     layers: [imageLayer],
-   *     cameraControls: new PanZoomControls(camera)
-   *   }]
-   * });
+   * Creates an Idetik runtime for the given canvas.
    *
-   * @example
-   * // Multiple viewports - one defaults to canvas, others use separate elements
-   * const idetik = new Idetik({
-   *   canvas: document.querySelector('canvas')!,
-   *   viewports: [
-   *     {
-   *       id: 'main',
-   *       // element omitted - defaults to canvas
-   *       camera: camera1,
-   *       layers: [layer1]
-   *     },
-   *     {
-   *       id: 'minimap',
-   *       element: document.querySelector('#minimap')!,
-   *       camera: camera2,
-   *       layers: [layer2]
-   *     }
-   *   ]
-   * });
-   *
-   * @throws {Error} If viewports have duplicate IDs or shared elements
+   * @param params - Initialization properties.
    */
   constructor(A) {
     this.canvas = A.canvas, this.renderer_ = new RQ(this.canvas);
@@ -3237,9 +3286,11 @@ class no {
         Q.updateSize(), this.renderer_.render(Q);
     });
   }
+  /** Counts of queued and in-flight chunk requests. */
   get chunkQueueStats() {
     return this.chunkManager_.queueStats;
   }
+  /** A snapshot of current CPU/GPU/JS heap memory usage. */
   get memoryStats() {
     const A = performance.memory;
     return {
@@ -3250,28 +3301,52 @@ class no {
       jsHeapLimitBytes: A?.jsHeapSizeLimit
     };
   }
+  /** The number of objects drawn in the last rendered frame. */
   get renderedObjects() {
     return this.renderer_.renderedObjects;
   }
+  /** The width of the rendering surface in pixels. */
   get width() {
     return this.renderer_.width;
   }
+  /** The height of the rendering surface in pixels. */
   get height() {
     return this.renderer_.height;
   }
+  /** The viewports in render order. */
   get viewports() {
     return this.viewports_;
   }
+  /** Whether the render loop is running. */
   get running() {
     return this.lastAnimationId_ !== void 0;
   }
+  /**
+   * Finds a viewport by its id.
+   *
+   * @param id - The id given in the viewport's definition.
+   * @returns The matching viewport or `undefined` if none matches.
+   */
   getViewport(A) {
     return this.viewports_.find((I) => I.id === A);
   }
+  /**
+   * Adds a viewport at runtime.
+   *
+   * @param props - The viewport definition. The `element` defaults to the
+   *   canvas and must be unique across viewports.
+   * @returns The created viewport.
+   */
   addViewport(A) {
     const [I] = gB([A], this.canvas, this.context_);
     return $B(I, this.viewports_), this.viewports_.push(I), this.running && (I.events.connect(), I.element !== this.canvas && this.sizeObserver_.observe(I.element)), k.info("Idetik", `Added viewport "${I.id}"`), I;
   }
+  /**
+   * Removes a previously added viewport.
+   *
+   * @param viewport - The viewport to remove.
+   * @returns `true` if the viewport was found and removed.
+   */
   removeViewport(A) {
     const I = this.viewports_.indexOf(A);
     return I === -1 ? (k.warn(
@@ -3279,16 +3354,37 @@ class no {
       `Viewport "${A.id}" not found, nothing to remove`
     ), !1) : (this.running && (A.events.disconnect(), A.element !== this.canvas && this.sizeObserver_.unobserve(A.element)), this.viewports_.splice(I, 1), k.info("Idetik", `Removed viewport "${A.id}"`), !0);
   }
+  /**
+   * Registers an overlay that updates once per frame.
+   *
+   * @param overlay - The overlay to add.
+   */
   addOverlay(A) {
     this.overlays.push(A);
   }
+  /**
+   * Removes a previously added overlay.
+   *
+   * @param overlay - The overlay to remove.
+   * @returns `true` if the overlay was found and removed.
+   */
   removeOverlay(A) {
     const I = this.overlays.indexOf(A);
     return I === -1 ? (k.warn("Idetik", "Overlay not found, nothing to remove"), !1) : (this.overlays.splice(I, 1), !0);
   }
+  /**
+   * Sets the memory budget for chunk data at runtime.
+   *
+   * @param memoryLimitMB - The new budget in megabytes.
+   */
   setMemoryLimitMB(A) {
     this.chunkManager_.memoryLimitBytes = A * 1024 * 1024;
   }
+  /**
+   * Starts the render loop and connects input handlers.
+   *
+   * @returns The instance, for chaining.
+   */
   start() {
     if (k.info("Idetik", "Idetik runtime starting"), this.running)
       k.warn("Idetik", "Idetik runtime already started");
@@ -3314,6 +3410,9 @@ class no {
       (B) => this.animate(B)
     );
   }
+  /**
+   * Stops the render loop and disconnects input handlers.
+   */
   stop() {
     if (k.info("Idetik", "Idetik runtime stopping"), !this.running)
       k.warn("Idetik", "Idetik runtime not started");
@@ -11989,7 +12088,9 @@ ${JSON.stringify(g)}`);
   }
 }
 class ZA {
+  /** The zarr store location the image was opened from. */
   location;
+  /** The OME-Zarr version passed at creation if any. */
   version;
   loader_;
   constructor(A) {
@@ -12017,33 +12118,45 @@ class ZA {
       );
     return new WE({ metadata: i, arrays: a, arrayParams: o });
   }
+  /**
+   * Returns per-axis dimension metadata for the image.
+   *
+   * Each axis entry lists one record per level of detail with its size,
+   * chunk size, scale, and translation. Use these to convert between
+   * array indices and world coordinates, pick slice coordinates, and
+   * frame cameras around the image extent.
+   */
   getDimensions() {
     return this.loader_.getSourceDimensionMap();
   }
+  /**
+   * Returns the number of channels in the image.
+   */
   getChannelCount() {
     return this.getDimensions().c?.lods[0].size ?? 1;
   }
+  /** The chunk loader that streams this image's data. */
   get loader() {
     return this.loader_;
   }
   /**
-   * Creates and opens an OmeZarrImageSource from an HTTP(S) URL.
+   * Opens an OME-Zarr image over HTTP(S).
    *
-   * @param props.url URL of the Zarr root
-   * @param props.version OME-Zarr version
+   * @param props - The store url and optional version.
    */
   static async fromHttp(A) {
     const I = new CA(new zA(A.url)), B = await ZA.openLoader(I, A.version);
     return new ZA({ location: I, version: A.version, loader: B });
   }
   /**
-   * Creates and opens an OmeZarrImageSource from a local filesystem directory.
+   * Opens an OME-Zarr image from a local directory.
+   *
+   * Uses the File System Access API so it only works in Chromium-based
+   * browsers. Pass the handle returned by `window.showDirectoryPicker()`.
+   * The optional path lets an application ask once for root permission
+   * and open many images.
    *
-   * @param directory return value of `window.showDirectoryPicker()` which gives the browser
-   *    permission to access a directory (only works in Chrome/Edge)
-   * @param version OME-Zarr version
-   * @param path path to image, beginning with "/". This argument allows the application to only
-   *    ask the user once for permission to the root directory
+   * @param props - The directory handle, optional version, and path.
    */
   static async fromFileSystem(A) {
     const I = new CA(
@@ -12054,14 +12167,33 @@ class ZA {
   }
 }
 class qI {
+  /**
+   * How the layer's output blends with previously drawn content. Also
+   * applies to blending between objects within the layer.
+   */
+  blendMode;
+  /**
+   * Whether the layer writes depth and hides content drawn behind it.
+   *
+   * Occluding layers render a depth pass and always draw before
+   * non-occluding layers regardless of their order in the viewport. When
+   * not set explicitly this value is inferred from `blendMode` at
+   * construction only. Reassigning {@link blendMode} later does not update
+   * it.
+   */
+  occludes;
+  /** Set to `true` by subclasses whose shaders read scene depth. */
+  requiresSceneDepth_ = !1;
   coverageGroups_ = /* @__PURE__ */ new Map();
   state_ = "initialized";
   attached_ = !1;
   callbacks_ = [];
   opacity_;
-  blendMode;
-  occludes;
-  requiresSceneDepth_ = !1;
+  /**
+   * Creates a layer with the given presentation state.
+   *
+   * @param props - Initialization properties.
+   */
   constructor({
     opacity: A = 1,
     blendMode: I = "none",
@@ -12069,20 +12201,41 @@ class qI {
   } = {}) {
     this.opacity_ = hA(A, 0, 1), this.blendMode = I, this.occludes = B ?? I === "none";
   }
+  /**
+   * Whether the layer's shaders read scene depth. When `true` the renderer
+   * draws occluding layers to a depth texture the layer's shaders can
+   * sample. A layer cannot both occlude and read scene depth.
+   */
   get requiresSceneDepth() {
     return this.requiresSceneDepth_;
   }
+  /** The layer's opacity in `[0, 1]`. Values outside are clamped. */
   get opacity() {
     return this.opacity_;
   }
+  /** @param value - The new opacity in `[0, 1]`. */
   set opacity(A) {
     (A < 0 || A > 1) && k.warn(
       "Layer",
       `Opacity out of bounds: ${A} — clamping to [0.0, 1.0]`
     ), this.opacity_ = hA(A, 0, 1);
   }
+  /**
+   * Handles a pointer or wheel event from the owning viewport. Called
+   * automatically for each event before the camera controls. The default
+   * implementation does nothing.
+   *
+   * @param _event - The event with clip and world coordinates attached.
+   */
   onEvent(A) {
   }
+  /**
+   * Lifecycle hook that is called automatically when a layer is
+   * is attached to a viewport. A layer can only be attached to one viewport
+   * at a time.
+   *
+   * @param context - The shared runtime context.
+   */
   onAttached(A) {
     if (this.attached_)
       throw new Error(
@@ -12092,42 +12245,79 @@ class qI {
       throw new Error(`${this.type} cannot both occlude and read scene depth.`);
     this.attach(A), this.attached_ = !0;
   }
+  /**
+   * Lifecycle hook that is called automatically when a layer is detached
+   * from a viewport.
+   *
+   * @param context - The shared runtime context.
+   */
   onDetached(A) {
     this.attached_ && (this.detach(A), this.attached_ = !1);
   }
+  /** @hidden */
   attach(A) {
   }
+  /** @hidden */
   detach(A) {
   }
+  /**
+   * The layer's renderable objects grouped by coverage group. Objects in
+   * a group draw each pixel at most once, letting chunks at multiple
+   * levels of detail overlap correctly.
+   */
   get coverageGroups() {
     return this.coverageGroups_;
   }
+  /** The layer's current lifecycle state. */
   get state() {
     return this.state_;
   }
+  /**
+   * Registers a callback invoked after every state change.
+   *
+   * @param callback - Receives the new and previous states.
+   */
   addStateChangeCallback(A) {
     this.callbacks_.push(A);
   }
+  /**
+   * Removes a previously registered state change callback.
+   *
+   * @param callback - The callback to remove.
+   */
   removeStateChangeCallback(A) {
     const I = this.callbacks_.indexOf(A);
     if (I === -1)
       throw new Error(`Callback to remove could not be found: ${A}`);
     this.callbacks_.splice(I, 1);
   }
+  /**
+   * Sets the lifecycle state and notifies state change callbacks.
+   *
+   * @param newState - The state to enter.
+   */
   setState(A) {
     const I = this.state_;
     this.state_ = A, this.callbacks_.forEach((B) => B(A, I));
   }
+  /**
+   * Registers a renderable object for drawing. Objects in the same
+   * coverage group draw each pixel at most once.
+   *
+   * @param object - The object to add.
+   * @param coverageGroup - The group key.
+   */
   addObject(A, I = null) {
     const B = this.coverageGroups_.get(I);
     B ? B.push(A) : this.coverageGroups_.set(I, [A]);
   }
+  /** Removes all registered renderable objects. */
   clearObjects() {
     this.coverageGroups_.clear();
   }
   /**
-   * Get uniforms for shader program. Override in derived classes that need custom uniforms.
-   * @returns Object containing uniform name-value pairs
+   * Returns uniform name-value pairs applied to every object drawn by
+   * this layer. Override in subclasses that need custom shader uniforms.
    */
   getUniforms() {
     return {};
@@ -12214,41 +12404,82 @@ class eC {
   rotation_ = hI();
   translation_ = d();
   scale_ = p(1, 1, 1);
+  /**
+   * Composes the given rotation onto the current rotation.
+   *
+   * @param q - The rotation to apply.
+   */
   addRotation(A) {
     EQ(this.rotation_, this.rotation_, A), this.dirty_ = !0;
   }
+  /**
+   * Replaces the rotation with the given quaternion.
+   *
+   * @param q - The new rotation.
+   */
   setRotation(A) {
     oQ(this.rotation_, A), this.dirty_ = !0;
   }
+  /** A copy of the rotation quaternion. */
   get rotation() {
     return iQ(this.rotation_);
   }
+  /**
+   * Adds the given offset to the translation.
+   *
+   * @param vec - The offset to add.
+   */
   addTranslation(A) {
     aI(this.translation_, this.translation_, A), this.dirty_ = !0;
   }
+  /**
+   * Replaces the translation with the given vector.
+   *
+   * @param vec - The new translation.
+   */
   setTranslation(A) {
     jI(this.translation_, A), this.dirty_ = !0;
   }
+  /** A copy of the translation vector. */
   get translation() {
     return EA(this.translation_);
   }
+  /**
+   * Multiplies the scale componentwise by the given vector.
+   *
+   * @param vec - The scale factors to apply.
+   */
   addScale(A) {
     zC(this.scale_, this.scale_, A), this.dirty_ = !0;
   }
+  /**
+   * Replaces the scale with the given vector.
+   *
+   * @param vec - The new scale.
+   */
   setScale(A) {
     jI(this.scale_, A), this.dirty_ = !0;
   }
+  /**
+   * Rotates the transform to face the given target point. Uses `+Y` as
+   * world up.
+   *
+   * @param target - The world-space point to face.
+   */
   targetTo(A) {
     Gg(this.translation_, A) && (A = EA(A), A[2] += T);
     const I = XC($(), this.translation_, A, fi), B = xC(VB(), I);
     wg(this.rotation_, B), MI(this.rotation_, this.rotation_), this.dirty_ = !0;
   }
+  /** A copy of the scale vector. */
   get scale() {
     return EA(this.scale_);
   }
+  /** The composed transform matrix. Recomputed when stale. */
   get matrix() {
     return this.dirty_ && (this.computeMatrix(), this.dirty_ = !1), this.matrix_;
   }
+  /** The inverse of the composed transform matrix. */
   get inverse() {
     return OA($(), this.matrix);
   }
@@ -12262,17 +12493,34 @@ class eC {
   }
 }
 class x {
+  /** Opaque red `#ff0000`. */
   static RED = new x(1, 0, 0);
+  /** Opaque green `#00ff00`. */
   static GREEN = new x(0, 1, 0);
+  /** Opaque blue `#0000ff`. */
   static BLUE = new x(0, 0, 1);
+  /** Opaque yellow `#ffff00`. */
   static YELLOW = new x(1, 1, 0);
+  /** Opaque magenta `#ff00ff`. */
   static MAGENTA = new x(1, 0, 1);
+  /** Opaque cyan `#00ffff`. */
   static CYAN = new x(0, 1, 1);
+  /** Opaque black `#000000`. */
   static BLACK = new x(0, 0, 0);
+  /** Opaque white `#ffffff`. */
   static WHITE = new x(1, 1, 1);
+  /** Fully transparent black. */
   static TRANSPARENT = new x(0, 0, 0, 0);
   // RGBA color values in the range [0, 1]
   rgba_;
+  /**
+   * Creates a color from RGBA components in `[0, 1]`.
+   *
+   * @param r - The red component.
+   * @param g - The green component.
+   * @param b - The blue component.
+   * @param a - The alpha component. Defaults to `1`.
+   */
   constructor(A, I, B, C) {
     if (A < 0 || A > 1 || I < 0 || I > 1 || B < 0 || B > 1)
       throw new Error("RGB values must be in the range [0, 1]");
@@ -12280,30 +12528,43 @@ class x {
       throw new Error("Alpha value must be in the range [0, 1]");
     this.rgba_ = [A, I, B, C ?? 1];
   }
+  /** The RGB components as a three-element array. */
   get rgb() {
     return [this.rgba_[0], this.rgba_[1], this.rgba_[2]];
   }
+  /** The RGBA components as a four-element array. */
   get rgba() {
     return this.rgba_;
   }
+  /** The red component. */
   get r() {
     return this.rgba_[0];
   }
+  /** The green component. */
   get g() {
     return this.rgba_[1];
   }
+  /** The blue component. */
   get b() {
     return this.rgba_[2];
   }
+  /** The alpha component. */
   get a() {
     return this.rgba_[3];
   }
+  /** The color as a `#rrggbb` hex string. Alpha is dropped. */
   get rgbHex() {
     return `#${this.toHexComponent(this.r)}${this.toHexComponent(this.g)}${this.toHexComponent(this.b)}`;
   }
+  /** The color packed into a 32-bit integer as RGBA bytes. */
   get packed() {
     return Math.round(this.r * 255) << 24 | Math.round(this.g * 255) << 16 | Math.round(this.b * 255) << 8 | Math.round(this.a * 255);
   }
+  /**
+   * Converts a {@link ColorLike} value to a `Color`.
+   *
+   * @param colorLike - The value to convert.
+   */
   static from(A) {
     if (A instanceof x)
       return A;
@@ -12313,6 +12574,11 @@ class x {
       return x.fromRgbHex(A);
     throw new Error("Unsupported color format");
   }
+  /**
+   * Parses a `#rrggbb` hex string into an opaque color.
+   *
+   * @param hex - The hex string with or without the leading `#`.
+   */
   static fromRgbHex(A) {
     const I = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(A);
     if (!I)
@@ -12330,8 +12596,17 @@ class x {
   }
 }
 class gI extends YI {
+  /**
+   * Draws the geometry's wireframe on top of the normal pass. Layers use
+   * this as a chunk debugging aid. Defaults to `false`.
+   */
   wireframeEnabled = !1;
+  /** The color of the wireframe overlay. Defaults to `Color.WHITE`. */
   wireframeColor = x.WHITE;
+  /**
+   * Whether the object is depth tested when drawn. Objects that opt out
+   * are also left out of the depth prepass. Defaults to `true`.
+   */
   depthTest = !0;
   textures_ = [];
   staleTextures_ = [];
@@ -12341,59 +12616,124 @@ class gI extends YI {
   programName_ = null;
   depthProgramName_ = null;
   cullFaceMode_ = "none";
+  /**
+   * Assigns a texture to the given texture unit. The renderer binds each
+   * entry of {@link textures} to its matching unit before drawing.
+   *
+   * @param index - The texture unit to bind to.
+   * @param texture - The texture to assign.
+   */
   setTexture(A, I) {
     this.textures_[A] = I;
   }
+  /**
+   * Removes all assigned textures.
+   */
   clearTextures() {
     this.textures_.length = 0;
   }
+  /**
+   * Queues a replaced texture for GPU disposal. Subclasses call this when
+   * swapping out a texture they own. The renderer drains the queue
+   * through {@link popStaleTextures} before the next draw. Passing
+   * `undefined` is a no-op.
+   *
+   * @param texture - The texture that is no longer in use.
+   */
   markStaleTexture(A) {
     A !== void 0 && this.staleTextures_.push(A);
   }
+  /**
+   * Drains the queue of textures marked stale. Called automatically by
+   * the renderer, which disposes the GPU resources of each returned
+   * texture.
+   *
+   * @returns The textures queued since the last call.
+   */
   popStaleTextures() {
     const A = this.staleTextures_;
     return this.staleTextures_ = [], A;
   }
+  /**
+   * The geometry drawn for this object.
+   */
   get geometry() {
     return this.geometry_;
   }
+  /**
+   * A line-segment version of {@link geometry} used for the wireframe
+   * overlay. Built lazily on first access and cached until the geometry
+   * changes.
+   */
   get wireframeGeometry() {
     return this.wireframeGeometry_ ??= new li(this.geometry), this.wireframeGeometry_;
   }
+  /** The assigned textures indexed by texture unit. */
   get textures() {
     return this.textures_;
   }
+  /**
+   * The object's world transform as translation, rotation, and scale.
+   * Layers position, orient, and size renderables through it.
+   */
   get transform() {
     return this.transform_;
   }
+  /** @param geometry - The geometry to draw. */
   set geometry(A) {
     this.geometry_ = A, this.wireframeGeometry_ = null;
   }
+  /**
+   * The name of a shader program that draws the object. The
+   * renderer skips objects whose program name is `null`.
+   */
   get programName() {
     return this.programName_;
   }
+  /**
+   * The name of the shader program used in the depth prepass or `null`
+   * to stay out of it. Objects without one never occlude other layers.
+   */
   get depthProgramName() {
     return this.depthProgramName_;
   }
+  /**
+   * The geometry's bounding box transformed to world space. The renderer
+   * culls objects whose box falls outside the view frustum.
+   */
   get boundingBox() {
     const A = this.geometry_.boundingBox.clone();
     return A.applyTransform(this.transform_.matrix), A;
   }
+  /**
+   * @param programName - The shader program name.
+   */
   set programName(A) {
     this.programName_ = A;
   }
+  /**
+   * Selects the shader program for the depth prepass. Subclasses set
+   * this so the object writes depth and occludes content in other
+   * layers.
+   *
+   * @param programName - The shader program name.
+   */
   set depthProgramName(A) {
     this.depthProgramName_ = A;
   }
+  /** Which triangle faces are culled when drawing. Defaults to `"none"`. */
   get cullFaceMode() {
     return this.cullFaceMode_;
   }
+  /** @param mode - The culling mode to apply. */
   set cullFaceMode(A) {
     this.cullFaceMode_ = A;
   }
   /**
-   * Get uniforms for shader program. Override in derived classes that need custom uniforms.
-   * @returns Object containing uniform name-value pairs
+   * Returns the uniform values to upload before drawing. Override in
+   * subclasses that need custom uniforms. Values are matched to shader
+   * uniforms by name and take precedence over the owning layer's
+   * uniforms.
    */
   getUniforms() {
     return {};
@@ -12402,24 +12742,35 @@ class gI extends YI {
 class pi extends gI {
   color_;
   width_;
+  /**
+   * Creates a projected line renderable for the given path geometry.
+   *
+   * @param props - Initialization properties.
+   */
   constructor({ geometry: A, color: I, width: B }) {
     super(), this.geometry = A, this.color_ = x.from(I), this.width_ = B, this.programName = "projectedLine", this.depthProgramName = "projectedLineDepth";
   }
+  /** Identifies the renderable type as `ProjectedLineRenderable`. */
   get type() {
     return "ProjectedLineRenderable";
   }
+  /** The line color. Assignable from any {@link ColorLike} value. */
   get color() {
     return this.color_;
   }
+  /** @param value - The new line color. */
   set color(A) {
     this.color_ = x.from(A);
   }
+  /** The line width in pixels. */
   get width() {
     return this.width_;
   }
+  /** @param value - The new width in pixels. */
   set width(A) {
     this.width_ = A;
   }
+  /** Returns the color and width uniforms for the line shader. */
   getUniforms() {
     return {
       u_lineColor: this.color.rgb,
@@ -12428,7 +12779,13 @@ class pi extends gI {
   }
 }
 class Ro extends qI {
+  /** Identifies the layer type as `AxesLayer`. */
   type = "AxesLayer";
+  /**
+   * Creates an axes layer with the given dimensions.
+   *
+   * @param props - Initialization properties.
+   */
   constructor(A) {
     super();
     const { length: I, width: B } = A;
@@ -12452,6 +12809,7 @@ class Ro extends qI {
       })
     ), this.setState("ready");
   }
+  /** Performs no per-frame work. The axes are built at construction. */
   update() {
   }
 }
@@ -12620,8 +12978,18 @@ class wC extends mA {
   }
 }
 class Ti extends gI {
-  channels_;
+  /**
+   * A matrix mapping world space to the texture's normalized coordinate
+   * space. Layers derive it from the chunk's offset, scale, and shape.
+   */
   worldToTexCoord = $();
+  channels_;
+  /**
+   * Creates an image renderable drawing the given texture. The texture's
+   * data type selects the matching scalar image shader.
+   *
+   * @param props - Initialization properties.
+   */
   constructor({
     width: A,
     height: I,
@@ -12630,12 +12998,27 @@ class Ti extends gI {
   }) {
     super(), this.geometry = new wC(A, I, 1, 1), this.setTexture(0, B), this.channels_ = tg(B, C), this.programName = xi(B), this.depthProgramName = "meshDepth";
   }
+  /** Identifies the renderable type as `ImageRenderable`. */
   get type() {
     return "ImageRenderable";
   }
+  /**
+   * Replaces the channel appearance settings and revalidates them
+   * against the current texture. Only the first entry affects rendering.
+   *
+   * @param channels - The new channel settings.
+   */
   setChannelProps(A) {
     this.channels_ = tg(this.textures[0], A);
   }
+  /**
+   * Updates one property of the channel at the given index and
+   * revalidates the channel against the current texture.
+   *
+   * @param channelIndex - The channel to update.
+   * @param property - The property name to set.
+   * @param value - The new value.
+   */
   setChannelProperty(A, I, B) {
     const C = jA(this.textures[0], {
       ...this.channels_[A],
@@ -12643,6 +13026,10 @@ class Ti extends gI {
     });
     this.channels_[A] = C;
   }
+  /**
+   * Returns the sampler, contrast, color, opacity, and world-to-texture
+   * uniforms for the scalar image shaders.
+   */
   getUniforms() {
     const A = this.textures[0];
     if (!A)
@@ -12737,6 +13124,7 @@ class xg {
   }
 }
 class rC extends qI {
+  /** Identifies the layer type as `ImageLayer`. */
   type = "ImageLayer";
   source_;
   sliceCoords_;
@@ -12764,6 +13152,11 @@ class rC extends qI {
     new x(0.4, 0.4, 0.7),
     new x(0.6, 0.5, 0.3)
   ];
+  /**
+   * Creates an image layer for the given source and slice.
+   *
+   * @param props - Initialization properties.
+   */
   constructor({
     source: A,
     sliceCoords: I,
@@ -12775,6 +13168,7 @@ class rC extends qI {
   }) {
     super({ blendMode: "additive", occludes: !0, ...i }), this.setState("initialized"), this.source_ = A, this.policy_ = B ?? ug(), this.sliceCoords_ = I, this.orientation_ = C ?? "XY", this.axes_ = MA(this.orientation_), this.planeRotation_ = dA(this.axes_), this.channelProps_ = Q, this.initialChannelProps_ = Q, this.onPickValue_ = E;
   }
+  /** @hidden */
   attach(A) {
     this.context_ = A, this.chunkStoreView_ = A.chunkManager.addView(
       this.source_,
@@ -12785,9 +13179,15 @@ class rC extends qI {
       this.chunkStoreView_.channelCount
     );
   }
+  /** @hidden */
   detach(A) {
     this.releaseAndRemoveChunks(this.visibleChunks_.keys()), this.orderedChunks_ = [], this.clearObjects(), this.chunkStoreView_?.dispose(), this.chunkStoreView_ = void 0, this.context_ = void 0;
   }
+  /**
+   * Streams chunks for the current view and refreshes the visible slice.
+   *
+   * @param viewport - The viewport being rendered.
+   */
   update(A) {
     if (!A || !this.chunkStoreView_) return;
     const I = A.camera, B = I.type === "OrthographicCamera" ? I.getWorldViewRect() : this.chunkStoreView_.getWholePlaneRect();
@@ -12798,12 +13198,16 @@ class rC extends qI {
     for (const [C, Q] of this.visibleChunks_)
       this.updateSlicePosition(Q, C);
   }
+  /** The slice plane the layer displays. */
   get orientation() {
     return this.orientation_;
   }
   /**
-   * Changes the slice orientation at runtime. Visible renderables are rebuilt
-   * for the new plane, chunks already resident in the shared cache are reused.
+   * Changes the slice orientation at runtime. Visible renderables are
+   * rebuilt for the new plane and chunks already resident in the shared
+   * cache are reused.
+   *
+   * @param orientation - The new slice plane.
    */
   setOrientation(A) {
     A !== this.orientation_ && (this.releaseAndRemoveChunks(this.visibleChunks_.keys()), this.orderedChunks_ = [], this.clearObjects(), this.chunkStoreView_?.dispose(), this.lastPresentationTimeStamp_ = void 0, this.lastPresentationTimeCoord_ = void 0, this.orientation_ = A, this.axes_ = MA(A), this.planeRotation_ = dA(this.axes_), this.context_ && (this.chunkStoreView_ = this.context_.chunkManager.addView(
@@ -12839,12 +13243,19 @@ class rC extends qI {
       I === void 0 || this.channelProps_?.[B]?.visible === !1 || this.addObject(I, B);
     }
   }
+  /** The `t` coordinate of the most recently presented slice. */
   get lastPresentationTimeCoord() {
     return this.lastPresentationTimeCoord_;
   }
   isPresentationStale() {
     return this.lastPresentationTimeStamp_ === void 0 ? !1 : performance.now() - this.lastPresentationTimeStamp_ > rC.STALE_PRESENTATION_MS_;
   }
+  /**
+   * Handles click picking for `onPickValue`. Called automatically for
+   * each pointer event.
+   *
+   * @param event - The event with clip and world coordinates attached.
+   */
   onEvent(A) {
     this.pointerDownPos_ = FC(
       A,
@@ -12866,18 +13277,30 @@ class rC extends qI {
     return i === null ? null : { world: E, value: i };
   }
   // exposed for use in chunk info overlay
+  /** The layer's chunk store view for diagnostic overlays. */
   get chunkStoreView() {
     return this.chunkStoreView_;
   }
+  /**
+   * The slice coordinates the layer displays. This is the object passed
+   * at construction and may be mutated to move through the data.
+   */
   get sliceCoords() {
     return this.sliceCoords_;
   }
+  /** The chunked image source the layer streams from. */
   get source() {
     return this.source_;
   }
+  /**
+   * The streaming policy in effect. Assign a new policy to reschedule
+   * loading at runtime, for example when switching between exploration
+   * and playback.
+   */
   get imageSourcePolicy() {
     return this.policy_;
   }
+  /** @param newPolicy - The policy to apply. */
   set imageSourcePolicy(A) {
     this.policy_ !== A && (this.policy_ = A, this.chunkStoreView_ && this.chunkStoreView_.setImageSourcePolicy(
       A,
@@ -12920,6 +13343,14 @@ class rC extends qI {
     const { u: B, v: C } = this.axes_;
     A.transform.setScale([I.scale[B], I.scale[C], 1]), A.transform.setRotation(this.planeRotation_), this.updateSlicePosition(A, I), A.worldToTexCoord = _B(I, this.axes_);
   }
+  /**
+   * Reads the data value at a world position from the resident chunks.
+   * Prefers the current level of detail and falls back to other resident
+   * levels.
+   *
+   * @param world - The world-space position to sample.
+   * @returns The sampled value or `null` if no resident chunk covers it.
+   */
   async getValueAtWorld(A) {
     const I = this.chunkStoreView_?.currentLOD ?? 0;
     for (const B of [!0, !1])
@@ -12941,17 +13372,26 @@ class rC extends qI {
     const s = { x: 0, y: 0, z: 0 };
     return s[Q] = o, s[E] = a, s[i] = this.sliceIndexForChunk(A), await I.textures[0].readTexel?.(s.x, s.y, s.z) ?? null;
   }
+  /** Whether chunk wireframes are drawn colored by level of detail. */
   get debugMode() {
     return this.debugMode_;
   }
+  /** @param debug - Whether to draw chunk wireframes. */
   set debugMode(A) {
     this.debugMode_ = A, this.visibleChunks_.forEach((I, B) => {
       I.wireframeEnabled = this.debugMode_, this.debugMode_ && (I.wireframeColor = this.wireframeColors_[B.lod % this.wireframeColors_.length]);
     });
   }
+  /** The current per-channel appearance settings. */
   get channelProps() {
     return this.channelProps_;
   }
+  /**
+   * Applies new per-channel appearance settings to all visible chunks
+   * and notifies channel change callbacks.
+   *
+   * @param channelProps - One entry per source channel.
+   */
   setChannelProps(A) {
     this.channelProps_ = A, this.visibleChunks_.forEach((I, B) => {
       I.setChannelProps(this.getChannelPropsForChunk(B));
@@ -12959,12 +13399,23 @@ class rC extends qI {
       I();
     });
   }
+  /** Restores the channel settings passed at construction. */
   resetChannelProps() {
     this.initialChannelProps_ !== void 0 && this.setChannelProps(this.initialChannelProps_);
   }
+  /**
+   * Registers a callback invoked after every channel settings change.
+   *
+   * @param callback - The callback to add.
+   */
   addChannelChangeCallback(A) {
     this.channelChangeCallbacks_.push(A);
   }
+  /**
+   * Removes a previously registered channel change callback.
+   *
+   * @param callback - The callback to remove.
+   */
   removeChannelChangeCallback(A) {
     const I = this.channelChangeCallbacks_.indexOf(A);
     if (I === -1)
@@ -13034,16 +13485,35 @@ class Wi extends mA {
   }
 }
 class bi extends gI {
+  /**
+   * World size of a voxel along each axis. Layers set it from the chunk
+   * scale so ray march steps account for anisotropic voxels. Defaults to
+   * `[1, 1, 1]`.
+   */
   voxelScale = p(1, 1, 1);
   channels_;
   loadedChannels_ = /* @__PURE__ */ new Set();
   channelToTextureIndex_ = /* @__PURE__ */ new Map();
+  /**
+   * Creates an empty volume renderable.
+   *
+   * @param props - Initialization properties.
+   */
   constructor({ channelProps: A = [] } = {}) {
     super(), this.geometry = new Wi(1, 1, 1, 1, 1, 1), this.cullFaceMode = "front", this.depthTest = !1, this.channels_ = [], this.setChannelProps(A);
   }
+  /** Identifies the renderable type as `VolumeRenderable`. */
   get type() {
     return "VolumeRenderable";
   }
+  /**
+   * Loads or refreshes the texture for the chunk's channel. The channel
+   * index comes from the chunk and the texture's data type selects the
+   * volume shader, so every channel must share one data type. Chunks
+   * without a texture are ignored.
+   *
+   * @param chunk - The chunk holding the channel texture.
+   */
   updateVolumeWithChunk(A) {
     if (!A.texture) return;
     const I = A.chunkIndex.c, B = this.channelToTextureIndex_.get(I);
@@ -13062,12 +13532,25 @@ class bi extends gI {
   updateChannelTexture(A, I) {
     this.setTexture(A, I);
   }
+  /**
+   * Marks all channels as not loaded so they stop rendering until the
+   * next chunk update. The textures themselves are kept.
+   */
   clearLoadedChannels() {
     this.loadedChannels_ = /* @__PURE__ */ new Set();
   }
+  /**
+   * Clears all textures and channel state so the renderable can be
+   * pooled and reused for another chunk.
+   */
   reset() {
     this.clearTextures(), this.channelToTextureIndex_.clear(), this.clearLoadedChannels();
   }
+  /**
+   * Returns per-channel sampler, color, contrast, opacity, and
+   * visibility uniforms for up to 4 loaded channels plus the voxel
+   * scale.
+   */
   getUniforms() {
     const A = [0, 0, 0, 0], I = [
       1,
@@ -13121,12 +13604,25 @@ class bi extends gI {
     const I = this.channelToTextureIndex_.values().next().value;
     return I !== void 0 ? this.textures[I] : null;
   }
+  /**
+   * Replaces the appearance settings for all channels.
+   *
+   * @param channels - The new channel settings.
+   */
   setChannelProps(A) {
     this.channels_ = tg(
       this.getAvailableChannelTexture(),
       A
     );
   }
+  /**
+   * Updates one property of the channel at the given index and
+   * revalidates it against the channel's texture when available.
+   *
+   * @param channelIndex - The channel to update.
+   * @param property - The property name to set.
+   * @param value - The new value.
+   */
   setChannelProperty(A, I, B) {
     const C = jA(
       this.getAvailableChannelTexture(A),
@@ -13154,7 +13650,17 @@ function Zi(g) {
 }
 const Pi = 2;
 class Uo extends qI {
+  /** Identifies the layer type as `VolumeLayer`. */
   type = "VolumeLayer";
+  /** Highlights rays of zero length for debugging. Defaults to `false`. */
+  debugShowDegenerateRays = !1;
+  /** Ray march step size relative to voxel size. Defaults to `1`. */
+  relativeStepSize = 1;
+  /** Scales sample opacity during compositing. Defaults to `1`. */
+  opacityMultiplier = 1;
+  /** Alpha where a ray stops early. Defaults to `0.99`. */
+  earlyTerminationAlpha = 0.99;
+  /** Volume ray marching reads scene depth to composite with occluding layers. */
   requiresSceneDepth_ = !0;
   source_;
   sliceCoords_;
@@ -13171,13 +13677,11 @@ class Uo extends qI {
   interactiveStepSizeScale_ = 1;
   // TODO: Make a debug config object to manage debug options
   debugShowWireframes_ = !1;
-  debugShowDegenerateRays = !1;
-  relativeStepSize = 1;
-  opacityMultiplier = 1;
-  earlyTerminationAlpha = 0.99;
+  /** Whether chunk bounding wireframes are drawn for debugging. */
   get debugShowWireframes() {
     return this.debugShowWireframes_;
   }
+  /** @param value - Whether to draw chunk wireframes. */
   set debugShowWireframes(A) {
     if (this.debugShowWireframes_ !== A) {
       for (const I of this.currentVolumes_.values())
@@ -13185,12 +13689,24 @@ class Uo extends qI {
       this.debugShowWireframes_ = A;
     }
   }
+  /**
+   * Sets the streaming policy at runtime and reschedules loading. The
+   * volume renders the level of detail given by the policy's `lod.min`.
+   *
+   * @param newPolicy - The policy to apply.
+   */
   set imageSourcePolicy(A) {
     this.policy_ !== A && (this.policy_ = A, this.chunkStoreView_ && this.chunkStoreView_.setImageSourcePolicy(
       A,
       dI
     ));
   }
+  /**
+   * Applies new per-channel appearance settings to all visible volumes
+   * and notifies channel change callbacks.
+   *
+   * @param channelProps - One entry per source channel.
+   */
   setChannelProps(A) {
     this.channelProps_ = A;
     for (const I of this.currentVolumes_.values())
@@ -13199,21 +13715,38 @@ class Uo extends qI {
       I();
     });
   }
+  /** The current per-channel appearance settings. */
   get channelProps() {
     return this.channelProps_;
   }
+  /** Restores the channel settings passed at construction. */
   resetChannelProps() {
     this.initialChannelProps_ !== void 0 && this.setChannelProps(this.initialChannelProps_);
   }
+  /**
+   * Registers a callback invoked after every channel settings change.
+   *
+   * @param callback - The callback to add.
+   */
   addChannelChangeCallback(A) {
     this.channelChangeCallbacks_.push(A);
   }
+  /**
+   * Removes a previously registered channel change callback.
+   *
+   * @param callback - The callback to remove.
+   */
   removeChannelChangeCallback(A) {
     const I = this.channelChangeCallbacks_.indexOf(A);
     if (I === -1)
       throw new Error(`Callback to remove could not be found: ${A}`);
     this.channelChangeCallbacks_.splice(I, 1);
   }
+  /**
+   * Creates a volume layer for the given source.
+   *
+   * @param props - Initialization properties.
+   */
   constructor({ source: A, sliceCoords: I, policy: B, channelProps: C }) {
     super({ blendMode: "premultipliedOver" }), this.source_ = A, this.sliceCoords_ = I, this.policy_ = B ?? ug(), this.initialChannelProps_ = C, this.channelProps_ = C, this.setState("initialized");
   }
@@ -13228,6 +13761,7 @@ class Uo extends qI {
     for (const E of I) Q.updateVolumeWithChunk(E);
     return this.updateVolumeTransform(Q, I[0]), Q;
   }
+  /** @hidden */
   attach(A) {
     this.chunkStoreView_ = A.chunkManager.addView(
       this.source_,
@@ -13237,6 +13771,7 @@ class Uo extends qI {
       this.chunkStoreView_.channelCount
     );
   }
+  /** @hidden */
   detach(A) {
     for (const I of this.currentVolumes_.values())
       this.releaseAndRemoveVolume(I);
@@ -13277,6 +13812,12 @@ class Uo extends qI {
   releaseAndRemoveVolume(A) {
     A.reset(), this.pool_.release(this.volumeToPoolKey_.get(A), A), this.volumeToPoolKey_.delete(A);
   }
+  /**
+   * Streams chunks for the current view and rebuilds the volume set
+   * sorted front to back. Called automatically once per frame.
+   *
+   * @param viewport - The viewport being rendered.
+   */
   update(A) {
     if (!A || !this.chunkStoreView_) return;
     this.chunkStoreView_.updateChunksForVolume(
@@ -13292,6 +13833,7 @@ class Uo extends qI {
     for (const B of I)
       this.addObject(B);
   }
+  /** Returns the ray marching uniforms for this layer. */
   getUniforms() {
     return {
       u_debugShowDegenerateRays: Number(this.debugShowDegenerateRays),
@@ -13390,17 +13932,32 @@ function Io(g) {
   return SC.has(g.dataType) ? "intLabelImage" : "labelImage";
 }
 class go extends gI {
+  /**
+   * A matrix mapping world space to the texture's normalized coordinate
+   * space. Layers derive it from the chunk's offset, scale, and shape.
+   */
+  worldToTexCoord = $();
   outlineSelected_;
   selectedValue_;
-  worldToTexCoord = $();
+  /**
+   * Creates a label renderable drawing the given label texture. The
+   * texture's data type selects the matching label shader.
+   *
+   * @param props - Initialization properties.
+   */
   constructor(A) {
     super(), this.geometry = new wC(A.width, A.height, 1, 1), this.setTexture(0, Ao(A.imageData));
     const I = JI(A.colorMap);
     this.setTexture(1, this.makeColorCycleTexture(I.cycle)), this.setTexture(2, this.makeColorLookupTableTexture(I.lookupTable)), this.outlineSelected_ = A.outlineSelected ?? !1, this.selectedValue_ = A.selectedValue ?? null, this.programName = Io(A.imageData), this.depthProgramName = "meshDepth";
   }
+  /** Identifies the renderable type as `LabelImageRenderable`. */
   get type() {
     return "LabelImageRenderable";
   }
+  /**
+   * Returns the sampler, color map, and selection uniforms for the label
+   * image shaders.
+   */
   getUniforms() {
     return {
       u_imageSampler: 0,
@@ -13411,10 +13968,23 @@ class go extends gI {
       u_worldToTexCoord: this.worldToTexCoord
     };
   }
+  /**
+   * Replaces the label color map. The previous color map textures are
+   * marked stale for GPU disposal.
+   *
+   * @param colorMap - The new color map.
+   */
   setColorMap(A) {
     const I = JI(A);
     this.markStaleTexture(this.textures[1]), this.markStaleTexture(this.textures[2]), this.setTexture(1, this.makeColorCycleTexture(I.cycle)), this.setTexture(2, this.makeColorLookupTableTexture(I.lookupTable));
   }
+  /**
+   * Sets the label value drawn as selected or `null` to clear the
+   * selection. The selected region is outlined when the renderable was
+   * constructed with `outlineSelected`.
+   *
+   * @param value - The label value to select.
+   */
   setSelectedValue(A) {
     this.selectedValue_ = A;
   }
@@ -13431,6 +14001,7 @@ class go extends gI {
   }
 }
 class RC extends qI {
+  /** Identifies the layer type as `LabelLayer`. */
   type = "LabelLayer";
   source_;
   sliceCoords_;
@@ -13450,6 +14021,11 @@ class RC extends qI {
   static STALE_PRESENTATION_MS_ = 1e3;
   lastPresentationTimeStamp_;
   lastPresentationTimeCoord_;
+  /**
+   * Creates a label layer for the given source and slice.
+   *
+   * @param props - Initialization properties.
+   */
   constructor({
     source: A,
     sliceCoords: I,
@@ -13462,6 +14038,7 @@ class RC extends qI {
   }) {
     super(o), this.setState("initialized"), this.source_ = A, this.policy_ = B ?? ug(), this.sliceCoords_ = I, this.orientation_ = C ?? "XY", this.axes_ = MA(this.orientation_), this.planeRotation_ = dA(this.axes_), this.colorMap_ = JI(Q), this.onPickValue_ = E, this.outlineSelected_ = i;
   }
+  /** @hidden */
   attach(A) {
     if (this.context_ = A, this.chunkStoreView_ = A.chunkManager.addView(
       this.source_,
@@ -13472,9 +14049,16 @@ class RC extends qI {
         `LabelLayer does not support multi-channel sources (found ${this.chunkStoreView_.channelCount} channels). Label data must be single-channel.`
       );
   }
+  /** @hidden */
   detach(A) {
     this.releaseAndRemoveChunks(this.visibleChunks_.keys()), this.clearObjects(), this.chunkStoreView_?.dispose(), this.chunkStoreView_ = void 0, this.context_ = void 0;
   }
+  /**
+   * Streams chunks for the current view and refreshes the visible slice.
+   * Called automatically once per frame.
+   *
+   * @param viewport - The viewport being rendered.
+   */
   update(A) {
     if (!A || !this.chunkStoreView_) return;
     const I = A.camera, B = I.type === "OrthographicCamera" ? I.getWorldViewRect() : this.chunkStoreView_.getWholePlaneRect();
@@ -13485,12 +14069,16 @@ class RC extends qI {
     for (const [C, Q] of this.visibleChunks_)
       this.updateSlicePosition(Q, C);
   }
+  /** The slice plane the layer displays. */
   get orientation() {
     return this.orientation_;
   }
   /**
-   * Changes the slice orientation at runtime. Visible renderables are rebuilt
-   * for the new plane, chunks already resident in the shared cache are reused.
+   * Changes the slice orientation at runtime. Visible renderables are
+   * rebuilt for the new plane and chunks already resident in the shared
+   * cache are reused.
+   *
+   * @param orientation - The new slice plane.
    */
   setOrientation(A) {
     A !== this.orientation_ && (this.releaseAndRemoveChunks(this.visibleChunks_.keys()), this.clearObjects(), this.chunkStoreView_?.dispose(), this.lastPresentationTimeStamp_ = void 0, this.lastPresentationTimeCoord_ = void 0, this.orientation_ = A, this.axes_ = MA(A), this.planeRotation_ = dA(this.axes_), this.context_ && (this.chunkStoreView_ = this.context_.chunkManager.addView(
@@ -13520,6 +14108,12 @@ class RC extends qI {
   isPresentationStale() {
     return this.lastPresentationTimeStamp_ === void 0 ? !1 : performance.now() - this.lastPresentationTimeStamp_ > RC.STALE_PRESENTATION_MS_;
   }
+  /**
+   * Handles click picking and selection outlining. Called automatically
+   * for each pointer event on the owning viewport.
+   *
+   * @param event - The event with clip and world coordinates attached.
+   */
   onEvent(A) {
     this.pointerDownPos_ = FC(
       A,
@@ -13542,28 +14136,52 @@ class RC extends qI {
     const i = await this.getValueAtWorld(E);
     return i === null ? null : { world: E, value: i };
   }
+  /** The validated color map currently in effect. */
   get colorMap() {
     return this.colorMap_;
   }
+  /**
+   * Replaces the color map and recolors all visible chunks.
+   *
+   * @param colorMap - Colors for label values. Omitted fields fall back
+   *   to defaults.
+   */
   setColorMap(A) {
     this.colorMap_ = JI(A), this.visibleChunks_.forEach((I) => {
       I.setColorMap(this.colorMap_);
     });
   }
+  /**
+   * Sets the label value drawn as selected or `null` to clear the
+   * selection.
+   *
+   * @param value - The label value to select.
+   */
   setSelectedValue(A) {
     this.selectedValue_ = A, this.visibleChunks_.forEach((I) => {
       I.setSelectedValue(this.selectedValue_);
     });
   }
+  /**
+   * The slice coordinates the layer displays. This is the object passed
+   * at construction and may be mutated to move through the data.
+   */
   get sliceCoords() {
     return this.sliceCoords_;
   }
+  /** The chunked label source the layer streams from. */
   get source() {
     return this.source_;
   }
+  /**
+   * The streaming policy in effect. Assign a new policy to reschedule
+   * loading at runtime, for example when switching between exploration
+   * and playback.
+   */
   get imageSourcePolicy() {
     return this.policy_;
   }
+  /** @param newPolicy - The policy to apply. */
   set imageSourcePolicy(A) {
     this.policy_ !== A && (this.policy_ = A, this.chunkStoreView_ && this.chunkStoreView_.setImageSourcePolicy(
       A,
@@ -13571,12 +14189,22 @@ class RC extends qI {
     ));
   }
   // exposed for use in chunk info overlay
+  /** The layer's chunk store view for diagnostic overlays. */
   get chunkStoreView() {
     return this.chunkStoreView_;
   }
+  /** The `t` coordinate of the most recently presented slice. */
   get lastPresentationTimeCoord() {
     return this.lastPresentationTimeCoord_;
   }
+  /**
+   * Reads the label value at a world position from the resident chunks.
+   * Prefers the current level of detail and falls back to other resident
+   * levels.
+   *
+   * @param world - The world-space position to sample.
+   * @returns The label value or `null` if no resident chunk covers it.
+   */
   async getValueAtWorld(A) {
     const I = this.chunkStoreView_?.currentLOD ?? 0;
     for (const B of [!0, !1])
@@ -13665,6 +14293,11 @@ const NC = {
   triangle: 2
 };
 class ko extends gI {
+  /**
+   * Creates a renderable drawing one marker per entry.
+   *
+   * @param points - The points to draw.
+   */
   constructor(A) {
     super(), this.programName = "points", this.depthProgramName = "pointsDepth";
     const I = A.flatMap((C) => {
@@ -13699,6 +14332,7 @@ class ko extends gI {
       offset: B.strideBytes
     }), this.geometry = B, this.setTexture(0, Co());
   }
+  /** Identifies the renderable type as `PointsRenderable`. */
   get type() {
     return "PointsRenderable";
   }
@@ -13733,6 +14367,152 @@ function Qo() {
   const o = new Bo(i, 256, 256);
   return o.wrapR = "clamp_to_edge", o.wrapS = "clamp_to_edge", o.wrapT = "clamp_to_edge", o;
 }
+class Eo {
+  planes_;
+  /**
+   * Creates a frustum from a view-projection matrix.
+   *
+   * @param m - The combined view-projection matrix.
+   */
+  constructor(A) {
+    this.planes_ = [
+      new sA(d(), 0),
+      new sA(d(), 0),
+      new sA(d(), 0),
+      new sA(d(), 0),
+      new sA(d(), 0),
+      new sA(d(), 0)
+    ], this.setWithViewProjection(A);
+  }
+  // Uses the fast plane-extraction algorithm described in
+  // Gribb & Hartmann (1997): https://tinyurl.com/5x5htcwm
+  /**
+   * Re-extracts the six planes from a view-projection matrix.
+   *
+   * @param m - The combined view-projection matrix.
+   */
+  setWithViewProjection(A) {
+    const I = d();
+    this.planes_[0].set(
+      rA(I, A[3] + A[0], A[7] + A[4], A[11] + A[8]),
+      A[15] + A[12]
+    ), this.planes_[1].set(
+      rA(I, A[3] - A[0], A[7] - A[4], A[11] - A[8]),
+      A[15] - A[12]
+    ), this.planes_[2].set(
+      rA(I, A[3] - A[1], A[7] - A[5], A[11] - A[9]),
+      A[15] - A[13]
+    ), this.planes_[3].set(
+      rA(I, A[3] + A[1], A[7] + A[5], A[11] + A[9]),
+      A[15] + A[13]
+    ), this.planes_[4].set(
+      rA(I, A[3] + A[2], A[7] + A[6], A[11] + A[10]),
+      A[15] + A[14]
+    ), this.planes_[5].set(
+      rA(I, A[3] - A[2], A[7] - A[6], A[11] - A[10]),
+      A[15] - A[14]
+    );
+    for (const B of this.planes_) B.normalize();
+  }
+  /**
+   * Tests whether a box is at least partly inside the frustum. The test
+   * is conservative. A box outside the frustum but near a corner can be
+   * reported as intersecting, which only costs a draw of an offscreen
+   * object.
+   *
+   * @param box - The world-space box to test.
+   */
+  intersectsWithBox3(A) {
+    const I = d();
+    for (const B of this.planes_) {
+      const C = B.normal;
+      if (I[0] = C[0] > 0 ? A.max[0] : A.min[0], I[1] = C[1] > 0 ? A.max[1] : A.min[1], I[2] = C[2] > 0 ? A.max[2] : A.min[2], B.signedDistanceToPoint(I) < 0) return !1;
+    }
+    return !0;
+  }
+}
+class cC extends YI {
+  transform_ = new eC();
+  /** @hidden */
+  projectionMatrix_ = $();
+  /** @hidden */
+  near_ = 0;
+  /** @hidden */
+  far_ = 0;
+  /** Recomputes the camera's projection matrix. */
+  update() {
+    this.updateProjectionMatrix();
+  }
+  /** The camera's projection matrix. */
+  get projectionMatrix() {
+    return this.projectionMatrix_;
+  }
+  /** The camera's world-space transform. */
+  get transform() {
+    return this.transform_;
+  }
+  /** The view matrix: the inverse of the camera's world transform. */
+  get viewMatrix() {
+    return this.transform.inverse;
+  }
+  /** The camera's local right axis in world space. */
+  get right() {
+    const A = this.transform.matrix;
+    return p(A[0], A[1], A[2]);
+  }
+  /** The camera's local up axis in world space. */
+  get up() {
+    const A = this.transform.matrix;
+    return p(A[4], A[5], A[6]);
+  }
+  /**
+   * Computes the combined view-projection matrix.
+   *
+   * @returns The projection matrix multiplied by the view matrix.
+   */
+  getViewProjection() {
+    return QI($(), this.projectionMatrix, this.viewMatrix);
+  }
+  /** The view frustum derived from the current view-projection. */
+  get frustum() {
+    return new Eo(this.getViewProjection());
+  }
+  /**
+   * Moves the camera by the given world-space offset.
+   *
+   * @param vec - The translation to add to the camera's position.
+   */
+  pan(A) {
+    this.transform.addTranslation(A);
+  }
+  /** The camera's world-space position. */
+  get position() {
+    return this.transform.translation;
+  }
+  /**
+   * Transforms a position from clip space to world space.
+   *
+   * @param position - The clip-space position to transform.
+   * @returns The corresponding world-space position.
+   */
+  clipToWorld(A) {
+    const I = DI(A[0], A[1], A[2], 1), B = OA(
+      $(),
+      this.projectionMatrix_
+    ), C = VA(
+      YA(),
+      I,
+      B
+    );
+    BQ(C, C, 1 / C[3]);
+    const Q = VA(
+      YA(),
+      C,
+      this.transform.matrix
+    );
+    return p(Q[0], Q[1], Q[2]);
+  }
+}
 class TB {
   radius;
   phi;
@@ -13749,7 +14529,7 @@ class TB {
     );
   }
 }
-const vI = -1, xB = 0, Eo = 1, WB = 9e-3, io = 1e-3, oo = 9e-4, ao = 0.5, so = 60;
+const vI = -1, xB = 0, io = 1, WB = 9e-3, oo = 1e-3, ao = 9e-4, so = 0.5, Do = 60;
 class Lo {
   camera_;
   orbitVelocity_ = new TB(0, 0, 0);
@@ -13758,32 +14538,49 @@ class Lo {
   currCenter_ = d();
   dampingFactor_;
   currMouseButton_ = vI;
+  /**
+   * Creates orbit controls and moves the camera to the initial pose.
+   *
+   * @param camera - The perspective camera to control.
+   * @param params - Initialization properties.
+   */
   constructor(A, I) {
     this.camera_ = A, this.currPos_ = new TB(
       I?.radius ?? 1,
       I?.yaw ?? 0,
       I?.pitch ?? 0
     ), I?.target && jI(this.currCenter_, I.target), this.dampingFactor_ = hA(
-      I?.dampingFactor ?? ao,
+      I?.dampingFactor ?? so,
       0,
       1
     ), this.updateCamera();
   }
+  /** The current distance from the target in world units. */
   get radius() {
     return this.currPos_.radius;
   }
+  /** The current azimuth angle in radians. */
   get yaw() {
     return this.currPos_.phi;
   }
+  /** The current elevation angle in radians. */
   get pitch() {
     return this.currPos_.theta;
   }
+  /** A copy of the point the camera orbits. */
   get target() {
     return EA(this.currCenter_);
   }
+  /** Whether any orbit, pan, or zoom velocity remains. */
   get isMoving() {
     return this.orbitVelocity_.phi !== 0 || this.orbitVelocity_.theta !== 0 || this.orbitVelocity_.radius !== 0 || this.panVelocity_[0] !== 0 || this.panVelocity_[1] !== 0 || this.panVelocity_[2] !== 0;
   }
+  /**
+   * Handles a pointer or wheel event. Called automatically by the owning
+   * viewport unless a layer stops propagation.
+   *
+   * @param event - The event with clip and world coordinates attached.
+   */
   onEvent(A) {
     switch (A.type) {
       case "pointerdown":
@@ -13801,13 +14598,19 @@ class Lo {
         break;
     }
   }
+  /**
+   * Applies pending velocities to the camera and decays them toward zero.
+   * Called automatically by the render loop once per frame.
+   *
+   * @param dt - Time since the last frame in seconds.
+   */
   onUpdate(A) {
     if (this.orbitVelocity_.phi === 0 && this.orbitVelocity_.theta === 0 && this.orbitVelocity_.radius === 0 && Gg(this.panVelocity_, p(0, 0, 0)))
       return;
     this.currPos_.phi += this.orbitVelocity_.phi, this.currPos_.theta += this.orbitVelocity_.theta, this.currPos_.radius += this.orbitVelocity_.radius * this.currPos_.radius, aI(this.currCenter_, this.currCenter_, this.panVelocity_);
     const I = Math.PI / 2 - T;
     this.currPos_.theta = hA(this.currPos_.theta, -I, I), this.currPos_.radius = Math.max(0.01, this.currPos_.radius), this.updateCamera();
-    const B = Math.pow(1 - this.dampingFactor_, A * so);
+    const B = Math.pow(1 - this.dampingFactor_, A * Do);
     this.orbitVelocity_.phi *= B, this.orbitVelocity_.theta *= B, this.orbitVelocity_.radius *= B, zI(this.panVelocity_, this.panVelocity_, B), this.cutoffLowVelocity();
   }
   onPointerDown(A) {
@@ -13816,7 +14619,7 @@ class Lo {
   }
   onPointerMove(A) {
     if (this.currMouseButton_ == vI) return;
-    const I = A.event, B = I.movementX ?? 0, C = I.movementY ?? 0, Q = this.currMouseButton_ === xB && !I.shiftKey, E = this.currMouseButton_ === xB && I.shiftKey || this.currMouseButton_ === Eo;
+    const I = A.event, B = I.movementX ?? 0, C = I.movementY ?? 0, Q = this.currMouseButton_ === xB && !I.shiftKey, E = this.currMouseButton_ === xB && I.shiftKey || this.currMouseButton_ === io;
     Q && this.orbit(B, C), E && this.pan(B, C);
   }
   onWheel(A) {
@@ -13834,11 +14637,11 @@ class Lo {
     this.orbitVelocity_.phi -= A * WB, this.orbitVelocity_.theta += I * WB;
   }
   pan(A, I) {
-    const B = this.currPos_.radius * io, C = d();
+    const B = this.currPos_.radius * oo, C = d();
     _I(C, C, this.camera_.right, A), _I(C, C, this.camera_.up, I), zI(C, C, B), $I(this.panVelocity_, this.panVelocity_, C);
   }
   zoom(A) {
-    this.orbitVelocity_.radius += A * oo;
+    this.orbitVelocity_.radius += A * ao;
   }
   updateCamera() {
     const A = aI(d(), this.currCenter_, this.currPos_.toVec3());
@@ -13848,107 +14651,6 @@ class Lo {
     Math.abs(this.orbitVelocity_.phi) < T && (this.orbitVelocity_.phi = 0), Math.abs(this.orbitVelocity_.theta) < T && (this.orbitVelocity_.theta = 0), Math.abs(this.orbitVelocity_.radius) < T && (this.orbitVelocity_.radius = 0), yg(this.panVelocity_) < T && $C(this.panVelocity_);
   }
 }
-class Do {
-  planes_;
-  constructor(A) {
-    this.planes_ = [
-      new sA(d(), 0),
-      new sA(d(), 0),
-      new sA(d(), 0),
-      new sA(d(), 0),
-      new sA(d(), 0),
-      new sA(d(), 0)
-    ], this.setWithViewProjection(A);
-  }
-  // Uses the fast plane-extraction algorithm described in
-  // Gribb & Hartmann (1997): https://tinyurl.com/5x5htcwm
-  setWithViewProjection(A) {
-    const I = d();
-    this.planes_[0].set(
-      rA(I, A[3] + A[0], A[7] + A[4], A[11] + A[8]),
-      A[15] + A[12]
-    ), this.planes_[1].set(
-      rA(I, A[3] - A[0], A[7] - A[4], A[11] - A[8]),
-      A[15] - A[12]
-    ), this.planes_[2].set(
-      rA(I, A[3] - A[1], A[7] - A[5], A[11] - A[9]),
-      A[15] - A[13]
-    ), this.planes_[3].set(
-      rA(I, A[3] + A[1], A[7] + A[5], A[11] + A[9]),
-      A[15] + A[13]
-    ), this.planes_[4].set(
-      rA(I, A[3] + A[2], A[7] + A[6], A[11] + A[10]),
-      A[15] + A[14]
-    ), this.planes_[5].set(
-      rA(I, A[3] - A[2], A[7] - A[6], A[11] - A[10]),
-      A[15] - A[14]
-    );
-    for (const B of this.planes_) B.normalize();
-  }
-  intersectsWithBox3(A) {
-    const I = d();
-    for (const B of this.planes_) {
-      const C = B.normal;
-      if (I[0] = C[0] > 0 ? A.max[0] : A.min[0], I[1] = C[1] > 0 ? A.max[1] : A.min[1], I[2] = C[2] > 0 ? A.max[2] : A.min[2], B.signedDistanceToPoint(I) < 0) return !1;
-    }
-    return !0;
-  }
-}
-class cC extends YI {
-  transform_ = new eC();
-  projectionMatrix_ = $();
-  near_ = 0;
-  far_ = 0;
-  update() {
-    this.updateProjectionMatrix();
-  }
-  get projectionMatrix() {
-    return this.projectionMatrix_;
-  }
-  get transform() {
-    return this.transform_;
-  }
-  get viewMatrix() {
-    return this.transform.inverse;
-  }
-  get right() {
-    const A = this.transform.matrix;
-    return p(A[0], A[1], A[2]);
-  }
-  get up() {
-    const A = this.transform.matrix;
-    return p(A[4], A[5], A[6]);
-  }
-  getViewProjection() {
-    return QI($(), this.projectionMatrix, this.viewMatrix);
-  }
-  get frustum() {
-    return new Do(this.getViewProjection());
-  }
-  pan(A) {
-    this.transform.addTranslation(A);
-  }
-  get position() {
-    return this.transform.translation;
-  }
-  clipToWorld(A) {
-    const I = DI(A[0], A[1], A[2], 1), B = OA(
-      $(),
-      this.projectionMatrix_
-    ), C = VA(
-      YA(),
-      I,
-      B
-    );
-    BQ(C, C, 1 / C[3]);
-    const Q = VA(
-      YA(),
-      C,
-      this.transform.matrix
-    );
-    return p(Q[0], Q[1], Q[2]);
-  }
-}
 const UC = 1.77, bB = 128, ZB = 128 / UC, ho = -1e6, to = 1e6;
 class Jo extends cC {
   // width_ and height_ should always be defined by constructor (see setFrame)
@@ -13962,27 +14664,48 @@ class Jo extends cC {
   /**
    * Creates an orthographic camera framing the given world-space rectangle.
    *
-   * @param props - The view frame edges in world units, near/far clipping
-   *   plane distances (default `-1e6` and `1e6`), and the slice orientation
-   *   the camera faces (default `"XY"`).
+   * @param props - Initialization properties.
    */
   constructor(A) {
     super(), this.near_ = A.near ?? ho, this.far_ = A.far ?? to, this.orientation_ = A.orientation ?? "XY", this.axes_ = MA(this.orientation_), this.rotation_ = dA(this.axes_), this.setFrame(A), this.updateProjectionMatrix();
   }
+  /**
+   * The world-space size of the rendered view as `[width, height]`.
+   *
+   * This is the camera frame padded to match the viewport's aspect ratio, so
+   * it reflects what is actually visible rather than the frame that was set.
+   */
   get viewportSize() {
     return this.viewportSize_;
   }
+  /**
+   * Sets the aspect ratio (width / height) of the viewport the camera renders
+   * into. Called automatically by the owning viewport when it resizes.
+   *
+   * @param aspectRatio - The viewport's width divided by its height.
+   */
   setAspectRatio(A) {
     this.viewportAspectRatio_ = A, this.updateProjectionMatrix();
   }
+  /**
+   * Reframes the camera to the given world-space rectangle, resetting any
+   * accumulated zoom and pan.
+   *
+   * The frame may be padded horizontally or vertically at render time to
+   * match the viewport's aspect ratio (see {@link viewportSize}).
+   *
+   * @param frame - The view frame edges in world units.
+   */
   setFrame({ left: A, right: I, top: B, bottom: C }) {
     this.width_ = Math.abs(I - A), this.height_ = Math.abs(B - C), this.updateProjectionMatrix();
     const Q = d();
     Q[W[this.axes_.u]] = 0.5 * (A + I), Q[W[this.axes_.v]] = 0.5 * (C + B), this.transform.setTranslation(Q), this.transform.setScale([1, 1, 1]), this.transform.setRotation(this.rotation_);
   }
+  /** Identifies the camera type as `OrthographicCamera`. */
   get type() {
     return "OrthographicCamera";
   }
+  /** The slice orientation the camera faces. */
   get orientation() {
     return this.orientation_;
   }
@@ -13990,6 +14713,8 @@ class Jo extends cC {
    * Changes the slice orientation the camera faces. The current frame and
    * zoom carry over numerically to the new plane axes. Call {@link setFrame}
    * to reframe the view for the new plane.
+   *
+   * @param orientation - The slice plane for the camera to face.
    */
   setOrientation(A) {
     if (A === this.orientation_)
@@ -13999,12 +14724,25 @@ class Jo extends cC {
     const C = d();
     C[W[this.axes_.u]] = I, C[W[this.axes_.v]] = B, this.transform.setTranslation(C), this.transform.setRotation(this.rotation_);
   }
+  /**
+   * Zooms the view by the given factor relative to the current zoom level.
+   * Factors greater than `1` zoom in and factors between `0` and `1` zoom
+   * out.
+   *
+   * @param factor - The magnification factor to apply.
+   */
   zoom(A) {
     if (A <= 0)
       throw new Error(`Invalid zoom factor: ${A}`);
     const I = 1 / A;
     this.transform.addScale([I, I, 1]);
   }
+  /**
+   * Computes the world-space rectangle currently visible in the viewport,
+   * accounting for zoom, pan, and aspect-ratio padding.
+   *
+   * @returns The visible rectangle on the camera's slice plane.
+   */
   getWorldViewRect() {
     let A = DI(-1, -1, 0, 1), I = DI(1, 1, 0, 1);
     const B = OA($(), this.getViewProjection());
@@ -14015,6 +14753,7 @@ class Jo extends cC {
       V(I[C], I[Q])
     );
   }
+  /** @hidden */
   updateProjectionMatrix() {
     const A = this.width_, I = this.height_, B = A / I;
     let C = 0.5 * A, Q = 0.5 * I;
@@ -14034,12 +14773,24 @@ class Yo {
   camera_;
   dragActive_ = !1;
   dragStart_ = d();
+  /**
+   * Creates pan and zoom controls for the given camera.
+   *
+   * @param camera - The orthographic camera to control.
+   */
   constructor(A) {
     this.camera_ = A;
   }
+  /** Whether a pan drag is in progress. */
   get isMoving() {
     return this.dragActive_;
   }
+  /**
+   * Handles a pointer or wheel event. Called automatically by the owning
+   * viewport unless a layer stops propagation.
+   *
+   * @param event - The event with clip and world coordinates attached.
+   */
   onEvent(A) {
     switch (A.type) {
       case "wheel":
@@ -14057,6 +14808,11 @@ class Yo {
         break;
     }
   }
+  /**
+   * Does nothing. Pan and zoom apply immediately with no inertia.
+   *
+   * @param _delta - Time since the last frame in seconds. Unused.
+   */
   onUpdate(A) {
   }
   onWheel(A) {
@@ -14086,6 +14842,11 @@ const yo = 60, eo = 1.77, oI = 0.1, XI = 180 - oI;
 class Mo extends cC {
   fov_;
   aspectRatio_;
+  /**
+   * Creates a perspective camera from the given projection settings.
+   *
+   * @param props - Initialization properties.
+   */
   constructor(A = {}) {
     const {
       fov: I = yo,
@@ -14100,20 +14861,40 @@ class Mo extends cC {
       );
     super(), this.fov_ = I, this.aspectRatio_ = B, this.near_ = C, this.far_ = Q, this.transform.setTranslation(E), this.updateProjectionMatrix();
   }
+  /**
+   * Sets the aspect ratio (width / height) of the viewport the camera
+   * renders into. Called automatically by the owning viewport when it
+   * resizes.
+   *
+   * @param aspectRatio - The viewport's width divided by its height.
+   */
   setAspectRatio(A) {
     this.aspectRatio_ = A, this.updateProjectionMatrix();
   }
+  /** Identifies the camera type as `PerspectiveCamera`. */
   get type() {
     return "PerspectiveCamera";
   }
+  /** The vertical field of view in degrees. */
   get fov() {
     return this.fov_;
   }
+  /**
+   * Zooms the view by the given factor relative to the current zoom level.
+   * Factors greater than `1` zoom in and factors between `0` and `1` zoom
+   * out.
+   *
+   * Zooming narrows or widens the field of view rather than moving the
+   * camera, and the result is clamped to valid angles.
+   *
+   * @param factor - The magnification factor to apply.
+   */
   zoom(A) {
     if (A <= 0)
       throw new Error(`Invalid zoom factor: ${A}`);
     this.fov_ = Math.max(oI, Math.min(XI, this.fov_ / A)), this.updateProjectionMatrix();
   }
+  /** @hidden */
   updateProjectionMatrix() {
     OC(
       this.projectionMatrix_,
@@ -14126,7 +14907,11 @@ class Mo extends cC {
 }
 export {
   Ro as AxesLayer,
+  AA as Box2,
+  SA as Box3,
+  cC as Camera,
   x as Color,
+  Eo as Frustum,
   no as Idetik,
   rC as ImageLayer,
   Ti as ImageRenderable,
@@ -14140,6 +14925,9 @@ export {
   Mo as PerspectiveCamera,
   ko as PointsRenderable,
   pi as ProjectedLineRenderable,
+  gI as RenderableObject,
+  eC as TrsTransform,
+  uQ as Viewport,
   Uo as VolumeLayer,
   bi as VolumeRenderable,
   ug as createExplorationPolicy,