@loaders.gl/tiles 5.0.0-alpha.6 → 5.0.0-alpha.7

package/src/tileset-3d/common/tile-3d-contracts.ts

@@ -0,0 +1,115 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Structural subset implemented by math.gl bounding volumes used by tile renderers. */
+export type Tile3DBoundingVolume = {
+  distanceSquaredTo?(point: unknown): number;
+  intersectPlane?(plane: unknown): number;
+};
+
+/** Renderer-neutral description of one ordered tile content entry. */
+export type Tile3DContent = {
+  /** Zero-based source order, stable across loading and unloading. */
+  index: number;
+  /** Resolved content URI when declared by the tileset. */
+  uri?: string;
+  /** Tileset group index declared by this content entry. */
+  group?: number;
+  /** Normalized tile content kind, when detected. */
+  type?: string;
+  /** Decoded payload, or null while unloaded/failed. */
+  payload: unknown;
+  /** Raw content metadata reference. */
+  metadata: Record<string, unknown> | null;
+  /** Transformed content volume, with tile-volume fallback. */
+  boundingVolume: Tile3DBoundingVolume | null;
+  /** Normalized feature-id declarations for this content. */
+  featureIds: Tile3DFeatureIdSet[];
+  /** Whether the payload can currently be rendered. */
+  renderable: boolean;
+};
+
+/** Renderer-neutral feature-id declaration from a tile content payload. */
+export type Tile3DFeatureIdSet = {
+  /** Source of the feature identifiers. */
+  source: 'attribute' | 'property-table' | 'constant' | 'texture' | 'implicit';
+  /** glTF attribute name for attribute-backed identifiers. */
+  attribute?: string;
+  /** Structural-metadata property-table index. */
+  propertyTable?: number;
+  /** Constant feature identifier. */
+  constant?: number;
+  /** Texture-backed identifier declaration, when present. */
+  texture?: Record<string, unknown>;
+  /** Implicit identifier declaration, when present. */
+  implicit?: Record<string, unknown>;
+  /** Decoded identifier values, when supplied by a content loader. */
+  values?: Uint32Array | Uint16Array | Uint8Array;
+  /** Unrecognized source fields preserved for forward compatibility. */
+  details?: Record<string, unknown>;
+};
+
+/** Raw metadata references inherited by a tile and its contents. */
+export type Tile3DMetadataContext = {
+  /** Tileset-level metadata entity. */
+  tileset?: Record<string, unknown> | null;
+  /** Group metadata entity selected for the tile's primary content. */
+  group?: Record<string, unknown> | null;
+  /** All tileset groups, used to resolve a selected content entry's group. */
+  groups?: readonly (Record<string, unknown> | null)[];
+  /** Tile metadata entity. */
+  tile?: Record<string, unknown> | null;
+  /** Content metadata entity. */
+  content?: Record<string, unknown> | null;
+  /** Implicit-subtree metadata entity. */
+  subtree?: Record<string, unknown> | null;
+};
+
+/** Extracts mesh-feature declarations from a decoded glTF-like payload. */
+export function getTile3DFeatureIdSets(payload: unknown): Tile3DFeatureIdSet[] {
+  const featureIdSets: Tile3DFeatureIdSet[] = [];
+  const visited = new Set<object>();
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== 'object') {
+      return;
+    }
+    if (visited.has(value as object)) {
+      return;
+    }
+    visited.add(value as object);
+    const record = value as Record<string, any>;
+    const declarations = record.extensions?.EXT_mesh_features?.featureIds;
+    if (Array.isArray(declarations)) {
+      for (const declaration of declarations) {
+        if (!declaration || typeof declaration !== 'object') {
+          continue;
+        }
+        const source = declaration.texture
+          ? 'texture'
+          : declaration.implicit
+            ? 'implicit'
+            : declaration.attribute !== undefined
+              ? 'attribute'
+              : declaration.propertyTable !== undefined
+                ? 'property-table'
+                : 'constant';
+        featureIdSets.push({
+          source,
+          attribute: declaration.attribute,
+          propertyTable: declaration.propertyTable,
+          constant: declaration.constant,
+          texture: declaration.texture,
+          implicit: declaration.implicit,
+          values: declaration.values,
+          details: declaration
+        });
+      }
+    }
+    for (const child of Object.values(record)) {
+      visit(child);
+    }
+  };
+  visit(payload);
+  return featureIdSets;
+}

package/src/tileset-3d/common/tile-3d.ts

@@ -8,6 +8,8 @@
 import {Vector3, Matrix4} from '@math.gl/core';
 import {CullingVolume} from '@math.gl/culling';
 import type {CullingResult} from '@math.gl/culling';
+import {getTile3DFeatureIdSets} from './tile-3d-contracts';
+import type {Tile3DContent, Tile3DFeatureIdSet, Tile3DMetadataContext} from './tile-3d-contracts';
 
 // Note: circular dependency
 import type {Tileset3D} from './tileset-3d';
@@ -85,6 +87,14 @@ export function getContentVisibility(
   return intersectingVolume ? 'intersecting' : 'inside';
 }
 
+function isNestedTilesetPayload(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object') {
+    return false;
+  }
+  const record = payload as Record<string, any>;
+  return record.shape === 'tileset3d' || record.type === 'tileset3d' || Boolean(record.tileset);
+}
+
 function defined(x) {
   return x !== undefined && x !== null;
 }
@@ -137,6 +147,9 @@ export class Tile3D {
    */
   private _unscaledLodMetricValue: number = 0;
 
+  /** Whether the source format defines geometric error in transform-local units. */
+  private _scaleGeometricError: boolean = true;
+
   /** @todo math.gl is not exporting BoundingVolume base type? */
   boundingVolume: any = null;
 
@@ -147,6 +160,14 @@ export class Tile3D {
   content: any = null;
   /** Loaded payloads in the same order as {@link contentUrls}; `content` remains the primary payload. */
   contents: any[] = [];
+  /** Ordered renderer-neutral descriptors for each source content entry. */
+  contentEntries: Tile3DContent[] = [];
+  /** Raw metadata references inherited by this tile and its content. */
+  metadataContext: Tile3DMetadataContext = {};
+  /** Feature-id declarations normalized from supported content extensions. */
+  featureIdSets: Tile3DFeatureIdSet[] = [];
+  /** Decoded 3D Tiles vector topology for the primary loaded content, when present. */
+  vectorContent: unknown = null;
   /**
    * Metadata entity attached to this tile in the source tileset, if present.
    *
@@ -228,6 +249,7 @@ export class Tile3D {
     return this._viewerRequestVolume;
   }
 
+  /** Accumulated tile transforms from the source JSON, excluding the tileset model matrix. */
   _initialTransform: Matrix4 = new Matrix4();
 
   // Used by traverser, cannot be marked private
@@ -283,11 +305,7 @@ export class Tile3D {
     this.type = header.type;
     this.contentUrl = header.contentUrl;
     this.contentUrls = header.contentUrls || (header.contentUrl ? [header.contentUrl] : []);
-    this.metadata = header.metadata || null;
-    const contentHeaders = Array.isArray(header.content) ? header.content : [header.content];
-    this.contentMetadata = contentHeaders
-      .filter(Boolean)
-      .map(contentHeader => contentHeader.metadata || null);
+    this._initializeMetadata(header);
     this.childrenState = header.implicitSubtree ? 'unloaded' : 'ready';
 
     this._initializeLodMetric(header);
@@ -295,6 +313,7 @@ export class Tile3D {
     this._updateLodMetricScale();
     this._initializeBoundingVolumes(header);
     this._initializeContent(header);
+    this._initializeContentEntries(header);
     this._initializeRenderingState(header);
 
     Object.seal(this);
@@ -407,12 +426,16 @@ export class Tile3D {
   }
 
   /**
-   * Get bounding box in cartographic coordinates
+   * Get the current world-space bounding volume in cartographic coordinates.
    * @returns [min, max] each in [longitude, latitude, altitude]
    */
   get boundingBox(): CartographicBounds {
     if (!this._boundingBox) {
-      this._boundingBox = getCartographicBounds(this.header.boundingVolume, this.boundingVolume);
+      this._boundingBox = getCartographicBounds(
+        this.header.boundingVolume,
+        this.boundingVolume,
+        !this.computedTransform.equals(this._initialTransform)
+      );
     }
     return this._boundingBox;
   }
@@ -585,6 +608,8 @@ export class Tile3D {
         this.contents = loadResult.contents;
         this.content = this.contents[0] || null;
       }
+      this.vectorContent =
+        this.contents.find(content => Boolean(content?.vectorContent))?.vectorContent || null;
 
       if (this.tileset.options.contentLoader) {
         await this.tileset.options.contentLoader(this);
@@ -592,6 +617,7 @@ export class Tile3D {
 
       this.contentState = TILE_CONTENT_STATE.READY;
       this._onContentLoaded();
+      this._updateContentEntriesAfterLoad(loadResult);
       return loadResult;
     } catch (error) {
       // Tile is unloaded before the content finishes loading
@@ -665,34 +691,137 @@ export class Tile3D {
   /**
    * Replaces a contentless implicit placeholder with its materialized subtree-root header.
    *
-   * Transform state is intentionally preserved: the placeholder already owns the composed
-   * transform, and reapplying the root transform here would double-transform bounds and geometric
-   * error. Content and raw geometric error are reinitialized from the newly available header.
+   * The placeholder transform is preserved when the subtree omits a root transform. An explicit
+   * subtree-root transform replaces it and is recomposed against the runtime parent. Content,
+   * metadata, bounds, and raw geometric error are reinitialized from the available header.
    *
    * @param materializedHeader - Available root header produced from one subtree resource.
    */
   applyImplicitSubtreeHeader(materializedHeader: Record<string, any>): void {
     const existingTransform = this.header.transform;
     const existingTransformMatrix = this.header.transformMatrix;
+    const hasMaterializedTransform = materializedHeader.transform !== undefined;
     this.header = {
       ...this.header,
       ...materializedHeader,
-      transform: existingTransform,
-      transformMatrix: existingTransformMatrix,
+      transform: hasMaterializedTransform ? materializedHeader.transform : existingTransform,
+      transformMatrix: hasMaterializedTransform
+        ? materializedHeader.transformMatrix
+        : existingTransformMatrix,
       implicitSubtree: undefined
     };
+    if (hasMaterializedTransform) {
+      this._initializeTransforms(this.header);
+    }
     this.refine = this._getRefine(materializedHeader.refine);
     this.type = materializedHeader.type;
     this.contentUrl = materializedHeader.contentUrl;
     this.contentUrls =
       materializedHeader.contentUrls ||
       (materializedHeader.contentUrl ? [materializedHeader.contentUrl] : []);
+    this._initializeMetadata(this.header);
     this._initializeLodMetric(materializedHeader);
     this._updateLodMetricScale();
     this._initializeBoundingVolumes(this.header);
+    this._boundingBox = undefined;
     // Use the merged header so inherited viewer-request-volume metadata remains available when a
     // materialized implicit tile has no render content of its own.
     this._initializeContent(this.header);
+    this._initializeContentEntries(this.header);
+  }
+
+  /** Refreshes tile and content metadata from a source or materialized tile header. */
+  private _initializeMetadata(header: Record<string, any>): void {
+    this.metadata = header.metadata || null;
+    const contentHeaders = Array.isArray(header.content) ? header.content : [header.content];
+    this.contentMetadata = contentHeaders
+      .filter(Boolean)
+      .map(contentHeader => contentHeader.metadata || null);
+    const firstContentHeader = contentHeaders.find(Boolean) || {};
+    const groupReference = firstContentHeader.group;
+    const group =
+      typeof groupReference === 'number'
+        ? this.tileset.groups?.[groupReference] || null
+        : groupReference || null;
+    const metadataContext: Tile3DMetadataContext = {
+      tileset: this.tileset.metadata || null,
+      group,
+      tile: this.metadata,
+      content: this.contentMetadata[0] || null,
+      subtree: header.implicitMetadata || null
+    };
+    if (this.tileset.groups) {
+      metadataContext.groups = this.tileset.groups;
+    }
+    this.metadataContext = metadataContext;
+  }
+
+  /** Updates payload and renderability while retaining immutable metadata descriptors. */
+  private _updateContentEntriesAfterLoad(loadResult: TileContentLoadResult): void {
+    if (loadResult.contentEntries) {
+      this.contentEntries = loadResult.contentEntries.map((entry, index) => ({
+        ...entry,
+        index,
+        boundingVolume:
+          entry.boundingVolume || this._contentBoundingVolumes[index] || this.boundingVolume,
+        payload: entry.payload ?? this.contents[index] ?? null,
+        featureIds: entry.featureIds?.length
+          ? entry.featureIds
+          : getTile3DFeatureIdSets(entry.payload ?? this.contents[index]),
+        renderable: Boolean(
+          entry.renderable !== false &&
+            (entry.payload ?? this.contents[index]) &&
+            !isNestedTilesetPayload(entry.payload ?? this.contents[index])
+        )
+      }));
+      this.featureIdSets = this.contentEntries.flatMap(entry => entry.featureIds);
+      return;
+    }
+    this.contentEntries = this.contentEntries.map((entry, index) => ({
+      ...entry,
+      payload: this.contents[index] ?? null,
+      featureIds: getTile3DFeatureIdSets(this.contents[index]),
+      renderable: Boolean(this.contents[index]) && !isNestedTilesetPayload(this.contents[index])
+    }));
+    this.featureIdSets = this.contentEntries.flatMap(entry => entry.featureIds);
+  }
+
+  /** Returns one ordered content descriptor, or null when the index is out of range. */
+  getContentEntry(index: number): Tile3DContent | null {
+    return this.contentEntries[index] || null;
+  }
+
+  /** Returns whether an ordered content entry currently has renderable payload. */
+  isContentRenderable(index: number): boolean {
+    return Boolean(this.contentEntries[index]?.renderable);
+  }
+
+  /** Initializes additive renderer-neutral descriptors from a normalized tile header. */
+  private _initializeContentEntries(tileHeader: Record<string, any>): void {
+    const headers = Array.isArray(tileHeader.content)
+      ? tileHeader.content
+      : tileHeader.content
+        ? [tileHeader.content]
+        : [];
+    this.contentEntries = headers.map((contentHeader, index) => {
+      const normalizedContentHeader = contentHeader || {};
+      return {
+        index,
+        uri: this.contentUrls[index] || normalizedContentHeader.uri || normalizedContentHeader.url,
+        group: normalizedContentHeader.group,
+        type: normalizedContentHeader.type,
+        payload: null,
+        metadata: normalizedContentHeader.metadata || null,
+        boundingVolume: this._contentBoundingVolumes[index] || this.boundingVolume,
+        featureIds: this._getFeatureIdSets(normalizedContentHeader),
+        renderable: false
+      };
+    });
+  }
+
+  /** Extracts renderer-neutral feature-id declarations without decoding property values. */
+  private _getFeatureIdSets(contentHeader: Record<string, any>): Tile3DFeatureIdSet[] {
+    return getTile3DFeatureIdSets(contentHeader);
   }
 
   // Unloads the tile's content.
@@ -704,6 +833,13 @@ export class Tile3D {
     }
     this.contents = [];
     this.content = null;
+    this.vectorContent = null;
+    this.contentEntries = this.contentEntries.map(entry => ({
+      ...entry,
+      payload: null,
+      renderable: false
+    }));
+    this.featureIdSets = this.contentEntries.flatMap(entry => entry.featureIds);
     if (this.header.content && this.header.content.destroy) {
       this.header.content.destroy();
     }
@@ -848,9 +984,15 @@ export class Tile3D {
    * @param frameState Current camera, culling, and optional clipping-plane state.
    * @returns The content visibility classification.
    */
-  contentVisibility(frameState: FrameState): CullingResult {
+  contentVisibility(frameState: FrameState, contentIndex?: number): CullingResult {
+    const contentVolumes =
+      contentIndex === undefined
+        ? this._contentBoundingVolumes
+        : this._contentBoundingVolumes[contentIndex]
+          ? [this._contentBoundingVolumes[contentIndex]]
+          : [];
     return getContentVisibility(
-      this._contentBoundingVolumes,
+      contentVolumes,
       this.boundingVolume,
       frameState.cullingVolume,
       this._visibilityPlaneMask,
@@ -913,6 +1055,10 @@ export class Tile3D {
 
   /** Initializes the tile's LOD metric from its header or its nearest available ancestor. */
   _initializeLodMetric(header: {[key: string]: any}): void {
+    this._scaleGeometricError =
+      typeof header._scaleGeometricError === 'boolean'
+        ? header._scaleGeometricError
+        : (this.parent?._scaleGeometricError ?? true);
     if ('lodMetricType' in header) {
       this.lodMetricType = header.lodMetricType;
     } else {
@@ -969,7 +1115,7 @@ export class Tile3D {
    * I3S `maxScreenThreshold` is already a screen-space metric and must not be transform-scaled.
    */
   _updateLodMetricScale(): void {
-    if (this.lodMetricType !== LOD_METRIC_TYPE.GEOMETRIC_ERROR) {
+    if (this.lodMetricType !== LOD_METRIC_TYPE.GEOMETRIC_ERROR || !this._scaleGeometricError) {
       this.lodMetricValue = this._unscaledLodMetricValue;
       return;
     }
@@ -1074,11 +1220,13 @@ export class Tile3D {
   }
 
   _updateBoundingVolume(header) {
+    this._boundingBox = undefined;
     // Update the bounding volumes
     this.boundingVolume = createBoundingVolume(
       header.boundingVolume,
       this.computedTransform,
-      this.boundingVolume
+      this.boundingVolume,
+      this._initialTransform
     );
 
     // Viewer request volumes constrain traversal, not just render content. A contentless implicit
@@ -1088,7 +1236,8 @@ export class Tile3D {
       this._viewerRequestVolume = createBoundingVolume(
         header.viewerRequestVolume,
         this.computedTransform,
-        this._viewerRequestVolume
+        this._viewerRequestVolume,
+        this._initialTransform
       );
     }
 
@@ -1106,7 +1255,12 @@ export class Tile3D {
     this._contentBoundingVolumes = contentHeaders.length
       ? contentHeaders.map(headerEntry =>
           headerEntry?.boundingVolume
-            ? createBoundingVolume(headerEntry.boundingVolume, this.computedTransform)
+            ? createBoundingVolume(
+                headerEntry.boundingVolume,
+                this.computedTransform,
+                undefined,
+                this._initialTransform
+              )
             : this.boundingVolume
         )
       : [this.boundingVolume];

package/src/tileset-3d/common/tileset-3d.ts

@@ -517,6 +517,26 @@ export class Tileset3D {
     return this._frameNumber;
   }
 
+  /**
+   * Returns the tiles requested during the most recent completed traversal.
+   *
+   * A defensive copy makes request ordering deterministic for diagnostics and prevents callers
+   * from mutating the scheduler's working set.
+   */
+  get requestedTiles(): readonly Tile3D[] {
+    return this._requestedTiles.slice();
+  }
+
+  /**
+   * Returns empty tiles considered during the most recent completed traversal.
+   *
+   * Empty tiles can still be useful hierarchy placeholders, but their IDs are included in
+   * observability snapshots so applications can distinguish traversal work from render content.
+   */
+  get emptyTiles(): readonly Tile3D[] {
+    return this._emptyTiles.slice();
+  }
+
   /**
    * Gets or sets the soft target, in bytes, for cached tile content not needed this frame.
    *
@@ -662,6 +682,14 @@ export class Tileset3D {
       return;
     }
     const preparedViewports = viewports instanceof Array ? viewports : [viewports];
+    const activeViewportIds = new Set(preparedViewports.map(viewport => viewport.id));
+    // A viewport may be removed between frames. Discard its completed state before aggregating
+    // requested and selected tiles so observability reflects only the current traversal inputs.
+    for (const frameStateId of Object.keys(this.frameStateData)) {
+      if (!activeViewportIds.has(frameStateId)) {
+        delete this.frameStateData[frameStateId];
+      }
+    }
 
     this._cache.reset();
     this._frameNumber++;
@@ -909,7 +937,7 @@ export class Tileset3D {
       if (
         initialMetadata?.tileset?.root &&
         typeof initialMetadata.tileset.root.then !== 'function' &&
-        !this.source.prepareTileset
+        (!this.source.prepareTileset || this.spatialReference?.status === 'native')
       ) {
         this.root = this._initializeTileHeaders(initialMetadata.tileset, null);
         this._applyViewState();

package/src/tileset-3d/common/tileset-observability.ts

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {Tileset3D} from './tileset-3d';
+import type {Tile3D} from './tile-3d';
+
+/**
+ * A deterministic, renderer-neutral snapshot of one {@link Tileset3D} traversal.
+ *
+ * Tile IDs are sorted so snapshots can be compared across runs even when child requests complete
+ * in a different order. Counts are reported for the completed traversal frame and cache values are
+ * expressed in bytes. This is an inspection contract; it does not alter traversal or request policy.
+ */
+export type Tileset3DTraversalSnapshot = {
+  /** Monotonically increasing traversal frame number. */
+  frameNumber: number;
+  /** IDs selected for rendering, sorted for stable comparisons. */
+  selectedTileIds: string[];
+  /** IDs whose content was requested, sorted for stable comparisons. */
+  requestedTileIds: string[];
+  /** IDs visited as hierarchy-only or empty tiles, sorted for stable comparisons. */
+  emptyTileIds: string[];
+  /** Number of selected tiles in the completed frame. */
+  visibleTileCount: number;
+  /** Number of selected tiles with renderable content. */
+  renderableTileCount: number;
+  /** Number of tile or subtree loads currently in flight. */
+  loadingTileCount: number;
+  /** Cumulative number of tiles loaded into the runtime cache. */
+  loadedTileCount: number;
+  /** Cumulative number of failed tile loads. */
+  failedTileCount: number;
+  /** Number of tiles currently retained in the runtime cache. */
+  cachedTileCount: number;
+  /** Estimated cached content bytes. */
+  cacheBytes: number;
+  /** Active memory-adjusted maximum SSE in logical/CSS pixels. */
+  maximumScreenSpaceError: number;
+  /** Source-specific implicit subtree counters, when the source exposes them. */
+  implicitTiling?: {
+    /** Number of subtree resources requested from the source. */
+    requestedSubtrees: number;
+    /** Number of subtree resources successfully materialized. */
+    loadedSubtrees: number;
+    /** Number of requests served by the parsed-subtree cache. */
+    cacheHits: number;
+    /** Number of parsed subtrees currently retained for reuse. */
+    cachedSubtrees: number;
+    /** Number of subtree requests currently in flight. */
+    pendingSubtrees: number;
+    /** Number of runtime tile headers created from materialized subtrees. */
+    materializedTiles: number;
+  };
+};
+
+/**
+ * Creates a stable observability snapshot from public {@link Tileset3D} state.
+ *
+ * The helper intentionally reads only public runtime fields and source diagnostics. It is safe to
+ * call from an instrumentation loop and does not retain tile or content references.
+ *
+ * @param tileset - Runtime whose most recent traversal should be inspected.
+ * @returns A serializable snapshot suitable for logs, regression fixtures, and benchmark output.
+ */
+export function getTileset3DTraversalSnapshot(tileset: Tileset3D): Tileset3DTraversalSnapshot {
+  const selectedTiles = tileset.selectedTiles.slice();
+  const requestedTiles = tileset.requestedTiles.slice();
+  const emptyTiles = tileset.emptyTiles.slice();
+
+  const getTileIds = (tiles: readonly Tile3D[]): string[] =>
+    tiles.map(tile => String(tile.id)).sort();
+
+  const getStatCount = (name: string): number => {
+    const count = tileset.stats.get(name).count;
+    return typeof count === 'number' && Number.isFinite(count) ? count : 0;
+  };
+
+  const implicitTilingSource = tileset.source as Tileset3D['source'] & {
+    getImplicitTilingStats?: () => Tileset3DTraversalSnapshot['implicitTiling'];
+  };
+  const implicitTiling = implicitTilingSource.getImplicitTilingStats?.();
+
+  return {
+    frameNumber: tileset.frameNumber,
+    selectedTileIds: getTileIds(selectedTiles),
+    requestedTileIds: getTileIds(requestedTiles),
+    emptyTileIds: getTileIds(emptyTiles),
+    visibleTileCount: selectedTiles.length,
+    renderableTileCount: selectedTiles.filter(
+      tile => tile.contentAvailable && Boolean(tile.content)
+    ).length,
+    loadingTileCount: getStatCount('Tiles Loading'),
+    loadedTileCount: getStatCount('Tiles Loaded'),
+    failedTileCount: getStatCount('Failed Tile Loads'),
+    cachedTileCount: getStatCount('Tiles In Memory'),
+    cacheBytes: tileset.gpuMemoryUsageInBytes,
+    maximumScreenSpaceError: tileset.memoryAdjustedScreenSpaceError,
+    ...(implicitTiling ? {implicitTiling} : {})
+  };
+}

package/src/tileset-3d/common/tileset-source.ts

@@ -10,6 +10,7 @@ import type {Tileset3D} from './tileset-3d';
 import type {FrameState} from '../helpers/frame-state';
 import type {TILESET_TYPE} from '../../constants';
 import type {TilesetSpatialReference} from '../../spatial/spatial-types';
+import type {Tile3DContent} from './tile-3d-contracts';
 
 /**
  * Parsed top-level tileset payload consumed by {@link Tileset3D} or a {@link Tileset3DSource}.
@@ -68,6 +69,8 @@ export type TileContentLoadResult = {
   loaded: boolean;
   /** All payloads loaded for a tile, in source order. */
   contents?: any[];
+  /** Optional normalized renderer-neutral descriptors for each content entry. */
+  contentEntries?: Tile3DContent[];
   /** Nested tileset metadata to install below the loaded tile, if any. */
   nestedTileset?: TilesetJSON;
   /** Nested tilesets found among multiple content payloads. */

package/src/tileset-3d/common/tileset-traverser.ts

@@ -219,9 +219,10 @@ export class TilesetTraverser {
         }
         stack.push(child);
         hasVisibleChild = true;
-      } else if (checkRefines || loadSiblings) {
-        // Keep non-visible children loaded since they are still needed before the parent can refine.
-        // Or loadSiblings is true so always load tiles regardless of visibility.
+      } else if ((checkRefines || loadSiblings) && child._inRequestVolume) {
+        // Keep non-visible children loaded when they are inside their viewer request volume;
+        // they may still be needed before a replacement parent can refine. The request-volume
+        // check intentionally applies to sibling loading as well, preventing off-volume work.
         this.loadTile(child, frameState);
         this.touchTile(child, frameState);
       }