@loaders.gl/tiles 5.0.0-alpha.1 → 5.0.0-alpha.11

package/src/tileset-3d/format-3d-tiles/tiles-3d-source.ts

@@ -2,14 +2,15 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {path} from '@loaders.gl/loader-utils';
+import {path, RequestCache, sliceArrayBuffer} from '@loaders.gl/loader-utils';
 import {Ellipsoid} from '@math.gl/geospatial';
-import {Vector3} from '@math.gl/core';
-import type {CoreAPI, LoaderOptions, LoaderWithParser} from '@loaders.gl/loader-utils';
+import {Matrix4, Vector3} from '@math.gl/core';
+import type {CoreAPI, Loader, LoaderContext, LoaderOptions} from '@loaders.gl/loader-utils';
 import type {Tile3D} from '../common/tile-3d';
 import {Tileset3DTraverser} from './tileset-3d-traverser';
 import type {Tileset3D} from '../common/tileset-3d';
 import type {
+  TileChildrenLoadResult,
   TileContentLoadResult,
   TilesetContentFormats,
   TilesetJSON,
@@ -24,6 +25,19 @@ import {Tile3D as Tile3DNode} from '../common/tile-3d';
 import {getZoomFromBoundingVolume} from '../helpers/zoom';
 import {TILESET_TYPE} from '../../constants';
 import type {TilesetTraverser, TilesetTraverserProps} from '../common/tileset-traverser';
+import type {FrameState} from '../helpers/frame-state';
+import {get3DTilesSpatialReference} from '../../spatial/format-spatial-reference';
+import {Tiles3DSpatialTransformer} from '../../spatial/tiles-3d-spatial-transformer';
+import {
+  applyTilesetSpatialOptions,
+  markTilesetSpatialReferenceTransformed
+} from '../../spatial/spatial-types';
+import type {TilesetSpatialReference} from '../../spatial/spatial-types';
+import {
+  materializeImplicitSubtree,
+  type ImplicitSubtreeReference,
+  type ParsedImplicitSubtree
+} from './implicit-tiling';
 
 const EMPTY_CONTENT_FORMATS: TilesetContentFormats = {
   draco: false,
@@ -32,6 +46,42 @@ const EMPTY_CONTENT_FORMATS: TilesetContentFormats = {
   ktx2: false
 };
 
+const DEFAULT_MAXIMUM_CACHED_SUBTREES = 32;
+
+type PackageFile = {
+  name?: string;
+  mimeType: string;
+  uri?: string;
+  originalUri?: string;
+  data?: ArrayBuffer;
+  byteOffset: number;
+  byteLength: number;
+  bufferUri?: string;
+};
+
+type PackageResource = {fileIndex: number; files: PackageFile[]};
+
+type Tiles3DPackageLoaderContext = LoaderContext & {
+  /** Parent package records available while parsing an embedded tileset or subtree. */
+  _tiles3dPackageFiles: PackageFile[];
+};
+
+/** Diagnostics for source-managed implicit subtree loading. */
+export type ImplicitTilingStats = {
+  /** Subtree resources requested from the resolver or core API. */
+  requestedSubtrees: number;
+  /** Successful subtree materializations, including parsed-cache hits. */
+  loadedSubtrees: number;
+  /** Requests served by the source's parsed-subtree cache. */
+  cacheHits: number;
+  /** Parsed subtree resources currently retained for reuse. */
+  cachedSubtrees: number;
+  /** Subtree resource requests currently in flight. */
+  pendingSubtrees: number;
+  /** Runtime headers created below already-existing subtree-root placeholders. */
+  materializedTiles: number;
+};
+
 /**
  * {@link Tileset3DSource} implementation for 3D Tiles datasets.
  */
@@ -39,7 +89,7 @@ export class Tiles3DSource implements Tileset3DSource {
   /** 3D Tiles format discriminator. */
   readonly type = TILESET_TYPE.TILES3D;
   /** Loader used for tile content requests. */
-  readonly loader: LoaderWithParser;
+  readonly loader: Loader;
   /** Root tileset URL. */
   readonly url: string;
   /** Base path used for relative tile resource resolution. */
@@ -65,9 +115,37 @@ export class Tiles3DSource implements Tileset3DSource {
   metadata?: TilesetSourceMetadata;
 
   private readonly queryParams: Record<string, string> = {};
+  /** Final request URLs cached by unmodified tile content URL. */
+  private readonly tileUrlCache: Map<string, string> = new Map();
+  /** Original content descriptors retained across {@link Tile3D.unloadContent} calls. */
+  private readonly tileContentHeaders = new WeakMap<Tile3D, Record<string, any>[]>();
+  /** Installed nested roots by parent placement and ordered nested-content slot, across reloads. */
+  private readonly nestedTilesetRoots = new WeakMap<Tile3D, Tile3D[]>();
+  /** Source-local namespaces assigned to distinct embedded glTF package file collections. */
+  private readonly packageNamespaces = new WeakMap<PackageFile[], number>();
+  /** Next source-local package namespace. */
+  private nextPackageNamespace = 0;
+  /** Parsed subtree requests keyed by final source URL for deduplication and LRU reuse. */
+  private readonly implicitSubtreeCache: RequestCache<ParsedImplicitSubtree>;
+  /** Mutable counters exposed as a defensive snapshot through {@link getImplicitTilingStats}. */
+  private readonly implicitTilingStats: Omit<
+    ImplicitTilingStats,
+    'cachedSubtrees' | 'pendingSubtrees'
+  > = {
+    requestedSubtrees: 0,
+    loadedSubtrees: 0,
+    cacheHits: 0,
+    materializedTiles: 0
+  };
+  /** Whether the owning tileset has released this source. */
+  private destroyed = false;
   private readonly extensionsUsed: string[] = [];
   private readonly resolver?: TilesetSourceResolver;
   private rootTileset: TilesetJSON;
+  /** CRS transformer shared by this source's headers and decoded glTF content. */
+  private spatialTransformer?: Tiles3DSpatialTransformer;
+  /** Root header after composing source-frame transforms and rebuilding target bounds. */
+  private preparedRootHeader?: Record<string, any>;
 
   /**
    * Creates a 3D Tiles source.
@@ -84,6 +162,25 @@ export class Tiles3DSource implements Tileset3DSource {
     this.resolver = request.resolver;
     this.coreApi = request.coreApi;
     this.loadOptions = loadOptions;
+    const maximumCachedSubtrees = Number(
+      (loadOptions['3d-tiles'] as Record<string, unknown> | undefined)?.maximumCachedSubtrees
+    );
+    const maximumCacheEntries = Number.isFinite(maximumCachedSubtrees)
+      ? Math.max(0, Math.floor(maximumCachedSubtrees))
+      : DEFAULT_MAXIMUM_CACHED_SUBTREES;
+    this.implicitSubtreeCache = new RequestCache({maxEntries: maximumCacheEntries});
+  }
+
+  /**
+   * Releases URL and parsed-subtree caches and blocks late subtree installation.
+   *
+   * The injected resolver or core API remains responsible for transport-level abort signals. A
+   * request that cannot be aborted may finish parsing, but it will not mutate destroyed tiles.
+   */
+  destroy(): void {
+    this.destroyed = true;
+    this.tileUrlCache.clear();
+    this.implicitSubtreeCache.clear();
   }
 
   /**
@@ -104,7 +201,9 @@ export class Tiles3DSource implements Tileset3DSource {
 
     if (this.rootTileset.queryString) {
       const searchParams = new URLSearchParams(this.rootTileset.queryString);
-      Object.assign(this.queryParams, Object.fromEntries(searchParams.entries()));
+      for (const [parameterName, parameterValue] of searchParams.entries()) {
+        this.setQueryParameter(parameterName, parameterValue);
+      }
     }
 
     this.asset = this.rootTileset.asset;
@@ -112,15 +211,16 @@ export class Tiles3DSource implements Tileset3DSource {
       throw new Error('Tileset must have an asset property.');
     }
     if (
+      this.rootTileset.formatVersion !== '2.0-draft' &&
       this.asset.version !== '0.0' &&
       this.asset.version !== '1.0' &&
       this.asset.version !== '1.1'
     ) {
-      throw new Error('The tileset must be 3D Tiles version either 0.0 or 1.0 or 1.1.');
+      throw new Error('The tileset must be 3D Tiles version 0.0, 1.0, 1.1, or 2.0-draft.');
     }
 
     if ('tilesetVersion' in this.asset) {
-      this.queryParams.v = this.asset.tilesetVersion;
+      this.setQueryParameter('v', this.asset.tilesetVersion);
     }
 
     this.properties = this.rootTileset.properties;
@@ -139,7 +239,8 @@ export class Tiles3DSource implements Tileset3DSource {
       tileset: this.rootTileset,
       lodMetricType: this.rootTileset.lodMetricType,
       lodMetricValue: this.rootTileset.lodMetricValue,
-      refine: this.rootTileset.root?.refine
+      refine: this.rootTileset.root?.refine,
+      spatialReference: get3DTilesSpatialReference(this.rootTileset)
     };
   }
 
@@ -160,15 +261,39 @@ export class Tiles3DSource implements Tileset3DSource {
     return this.getMetadata().tileset;
   }
 
+  /** Prepare nonlinear CRS state before runtime headers are materialized. */
+  async prepareTileset(tileset: Tileset3D): Promise<void> {
+    const spatialReference = tileset.spatialReference;
+    if (spatialReference.status === 'unresolved') {
+      throw new Error(
+        spatialReference.warnings[0] ||
+          '3D Tiles spatial operations cannot be resolved from the supplied metadata and options'
+      );
+    }
+    if (spatialReference.status !== 'transformable' && spatialReference.status !== 'transformed') {
+      return;
+    }
+    this.spatialTransformer ||= new Tiles3DSpatialTransformer(
+      spatialReference,
+      tileset.options.spatial
+    );
+    tileset.spatialReference = markTilesetSpatialReferenceTransformed(spatialReference);
+    this.preparedRootHeader = this.transformTileHeader(
+      this.getMetadata().tileset.root,
+      new Matrix4()
+    );
+  }
+
   /**
-   * Builds the eager runtime tile tree for a 3D Tiles subtree.
+   * Builds explicit runtime headers while leaving implicit subtree references lazy.
    */
   initializeTileHeaders(
     tileset: Tileset3D,
     tilesetJson: TilesetJSON,
     parentTile?: Tile3D | null
   ): Tile3D {
-    const rootTile = new Tile3DNode(tileset, tilesetJson.root, parentTile || undefined);
+    const rootHeader = parentTile ? tilesetJson.root : this.preparedRootHeader || tilesetJson.root;
+    const rootTile = new Tile3DNode(tileset, rootHeader, parentTile || undefined);
 
     if (parentTile) {
       parentTile.children.push(rootTile);
@@ -186,7 +311,7 @@ export class Tiles3DSource implements Tileset3DSource {
           const url = new URL(childTile.contentUrl);
           const session = url.searchParams.get('session');
           if (session) {
-            this.queryParams.session = session;
+            this.setQueryParameter('session', session);
           }
         }
         tile.children.push(childTile);
@@ -209,36 +334,241 @@ export class Tiles3DSource implements Tileset3DSource {
    * Loads binary content or nested tileset JSON for a runtime tile.
    */
   async loadTileContent(tile: Tile3D): Promise<TileContentLoadResult> {
-    const contentUrl = this.getTileUrl(tile.contentUrl);
+    const contentUrls = (tile.contentUrls || [tile.contentUrl]).filter(Boolean);
+    const cachedContentHeaders = this.tileContentHeaders.get(tile);
+    const contentHeaders: Record<string, any>[] =
+      cachedContentHeaders ||
+      (Array.isArray(tile.header?.content)
+        ? tile.header.content
+        : tile.header?.content
+          ? [tile.header.content]
+          : []);
+    if (!cachedContentHeaders) {
+      this.tileContentHeaders.set(tile, contentHeaders);
+    }
     const tilesetLoaderOptions =
       (this.loadOptions[this.loader.id] as Record<string, unknown>) || {};
     const options = {
       ...this.loadOptions,
       [this.loader.id]: {
         ...tilesetLoaderOptions,
-        isTileset: tile.type === 'json',
-        assetGltfUpAxis: (this.asset && this.asset.gltfUpAxis) || 'Y'
+        // Content bytes, rather than URL suffixes, distinguish external tilesets from renderable
+        // payloads. This is required for signed and extensionless resources.
+        isTileset: 'auto',
+        assetGltfUpAxis: (this.asset && this.asset.gltfUpAxis) || 'Y',
+        _tilesetOptions: {
+          spatialReference: tile.header?._spatialReference || tile.tileset?.spatialReference,
+          spatialOptions: tile.tileset?.options.spatial,
+          spatialTransform: tile.header?._spatialTransform
+        }
       }
     };
 
-    const content = await this.loadResourceData(contentUrl, options);
-    tile.content = content;
+    const contents = await Promise.all(
+      contentUrls.map((contentUrl, contentIndex) => {
+        const contentHeader = contentHeaders[contentIndex] || {};
+        const vectorExtension = contentHeader.extensions?.['3DTILES_content_gltf_vector'];
+        const vectorContent =
+          contentHeader._vectorContent ||
+          (vectorExtension?.vector === true ? {clip: vectorExtension.clip === true} : undefined);
+        const contentOptions = vectorContent
+          ? {
+              ...options,
+              [this.loader.id]: {
+                ...(options[this.loader.id] as Record<string, unknown>),
+                vectorContent
+              }
+            }
+          : options;
+        return this.loadContentResource(
+          this.getTileUrl(contentUrl),
+          contentHeader._resource,
+          contentOptions
+        );
+      })
+    );
+    tile.contents = contents;
+    tile.content = contents[0] || null;
+    const nestedTilesets = contents.filter(content => content?.shape === 'tileset3d');
 
     return {
       loaded: true,
-      nestedTileset: tile.contentUrl.includes('.json') ? content : undefined
+      contents,
+      nestedTileset: nestedTilesets[0],
+      nestedTilesets
+    };
+  }
+
+  /** Transform a tile header and its eagerly declared descendants. */
+  private transformTileHeader(
+    header: Record<string, any>,
+    parentTransform: Matrix4 = new Matrix4()
+  ): Record<string, any> {
+    if (!this.spatialTransformer) {
+      return header;
+    }
+    return this.transformTileHeaderWithTransformer(
+      header,
+      this.spatialTransformer,
+      parentTransform
+    );
+  }
+
+  /** Rebuilds one header subtree using an explicitly selected CRS transformer. */
+  private transformTileHeaderWithTransformer(
+    header: Record<string, any>,
+    transformer: Tiles3DSpatialTransformer,
+    parentTransform: Matrix4,
+    spatialReference?: TilesetSpatialReference
+  ): Record<string, any> {
+    const localTransform = header.transform ? new Matrix4(header.transform) : new Matrix4();
+    const composedTransform = new Matrix4(parentTransform).multiplyRight(localTransform);
+    const content = Array.isArray(header.content)
+      ? header.content.map((entry: Record<string, any>) =>
+          this.transformContentHeader(entry, composedTransform, transformer)
+        )
+      : header.content
+        ? this.transformContentHeader(header.content, composedTransform, transformer)
+        : header.content;
+    return {
+      ...header,
+      transform: undefined,
+      boundingVolume: header.boundingVolume
+        ? transformer.transformBoundingVolume(header.boundingVolume, composedTransform)
+        : header.boundingVolume,
+      _spatialReference: spatialReference,
+      _spatialTransform: composedTransform.toArray(),
+      content,
+      children: Array.isArray(header.children)
+        ? header.children.map((child: Record<string, any>) =>
+            this.transformTileHeaderWithTransformer(
+              child,
+              transformer,
+              composedTransform,
+              spatialReference
+            )
+          )
+        : header.children
+    };
+  }
+
+  private transformContentHeader(
+    content: Record<string, any>,
+    composedTransform: Matrix4,
+    transformer: Tiles3DSpatialTransformer
+  ): Record<string, any> {
+    return {
+      ...content,
+      boundingVolume: content.boundingVolume
+        ? transformer.transformBoundingVolume(content.boundingVolume, composedTransform)
+        : content.boundingVolume
+    };
+  }
+
+  /**
+   * Loads, materializes, and installs exactly one implicit subtree.
+   *
+   * Final URLs pass through the same query inheritance and archive/custom resolver path as render
+   * content. Parsed resources are deduplicated by final URL, while the pure materializer creates
+   * lazy placeholders for every available child subtree instead of recursively fetching them.
+   *
+   * @param tile - Existing contentless subtree-root placeholder.
+   * @param frameState - View state that made this request eligible; priority is consumed earlier.
+   * @returns Counts describing the installed subtree.
+   */
+  async loadTileChildren(tile: Tile3D, frameState: FrameState): Promise<TileChildrenLoadResult> {
+    void frameState;
+    const reference = tile.header.implicitSubtree as ImplicitSubtreeReference | undefined;
+    if (!reference) {
+      return {loaded: false, tileCount: 0, childSubtreeCount: 0};
+    }
+
+    const subtreeUrl = this.getTileUrl(reference.subtreeUrl);
+    const subtree = await this.loadImplicitSubtreeResource(subtreeUrl, reference.resource);
+    if (this.destroyed || tile.isDestroyed()) {
+      return {loaded: false, tileCount: 0, childSubtreeCount: 0};
+    }
+    const materializedSubtree = materializeImplicitSubtree(subtree, {
+      ...reference,
+      subtreeUrl
+    });
+
+    const nestedSpatialReference = tile.header._spatialReference as
+      | TilesetSpatialReference
+      | undefined;
+    const subtreeTransformer = nestedSpatialReference
+      ? new Tiles3DSpatialTransformer(nestedSpatialReference, tile.tileset.options.spatial)
+      : this.spatialTransformer;
+    const materializedRoot = subtreeTransformer
+      ? this.transformTileHeaderWithTransformer(
+          materializedSubtree.root,
+          subtreeTransformer,
+          new Matrix4(),
+          nestedSpatialReference
+        )
+      : materializedSubtree.root;
+    tile.applyImplicitSubtreeHeader(materializedRoot);
+    const materializedTileCount = this.initializeMaterializedChildren(
+      tile.tileset,
+      tile,
+      materializedRoot.children
+    );
+    this.implicitTilingStats.loadedSubtrees++;
+    this.implicitTilingStats.materializedTiles += materializedTileCount;
+
+    return {
+      loaded: true,
+      tileCount: materializedSubtree.tileCount,
+      childSubtreeCount: materializedSubtree.childSubtreeCount
+    };
+  }
+
+  /** Loads an implicit subtree for dataset traversal without camera state. */
+  async loadTileChildrenForTraversal(
+    tile: Tile3D,
+    signal?: AbortSignal
+  ): Promise<TileChildrenLoadResult> {
+    throwIfTraversalAborted(signal);
+    const result = await this.loadTileChildren(tile, {} as FrameState);
+    throwIfTraversalAborted(signal);
+    return result;
+  }
+
+  /**
+   * Returns a snapshot of implicit-subtree request, cache, and materialization counters.
+   *
+   * @returns Immutable-by-convention diagnostic values for runtime inspection.
+   */
+  getImplicitTilingStats(): ImplicitTilingStats {
+    return {
+      ...this.implicitTilingStats,
+      cachedSubtrees: this.implicitSubtreeCache.size - this.implicitSubtreeCache.pendingSize,
+      pendingSubtrees: this.implicitSubtreeCache.pendingSize
     };
   }
 
   /**
    * Resolves a tile content URL with source-managed query parameters.
+   *
+   * Existing per-resource parameters take precedence over inherited root, version, and session
+   * values. Completed URLs are cached by the original tile path; {@link setQueryParameter}
+   * invalidates the cache before changed source state can be observed.
+   *
+   * @param tilePath - Unmodified absolute content URL or data URL from the tile header.
+   * @returns Content URL with any missing source parameters appended.
    */
   getTileUrl(tilePath: string): string {
     if (tilePath.startsWith('data:')) {
       return tilePath;
     }
 
+    const cachedTileUrl = this.tileUrlCache.get(tilePath);
+    if (cachedTileUrl) {
+      return cachedTileUrl;
+    }
+
     if (!Object.keys(this.queryParams).length) {
+      this.tileUrlCache.set(tilePath, tilePath);
       return tilePath;
     }
 
@@ -252,7 +582,27 @@ export class Tiles3DSource implements Tileset3DSource {
     }
 
     const queryParams = mergedQueryParams.toString();
-    return queryParams ? `${pathWithoutQuery}?${queryParams}` : pathWithoutQuery;
+    const tileUrl = queryParams ? `${pathWithoutQuery}?${queryParams}` : pathWithoutQuery;
+    this.tileUrlCache.set(tilePath, tileUrl);
+    return tileUrl;
+  }
+
+  /**
+   * Updates an inherited source query parameter and invalidates derived request URLs.
+   *
+   * Root tokens and tileset versions normally settle during initialization. Some providers expose
+   * a session parameter on a child URL, so invalidation is required to prevent URLs cached earlier
+   * in header construction from retaining stale authentication state.
+   *
+   * @param parameterName - Query parameter name.
+   * @param parameterValue - Query parameter value.
+   */
+  private setQueryParameter(parameterName: string, parameterValue: string): void {
+    if (this.queryParams[parameterName] === parameterValue) {
+      return;
+    }
+    this.queryParams[parameterName] = parameterValue;
+    this.tileUrlCache.clear();
   }
 
   /**
@@ -297,10 +647,13 @@ export class Tiles3DSource implements Tileset3DSource {
   }
 
   /**
-   * Updates content-format flags and installs nested tileset subtrees.
+   * Updates content-format flags and installs nested tileset subtrees once per content slot.
+   * Reloading payloads retains attached roots and their descendants, including duplicate URLs
+   * declared in separate slots or parent placements. Detached roots are reinstalled in declaration order.
    */
   onTileLoaded(tileset: Tileset3D, tile: Tile3D, loadResult: TileContentLoadResult): void {
-    const {extensionsRemoved = []} = tile.content?.gltf || {};
+    const contents = tile.contents.length ? tile.contents : [tile.content];
+    const extensionsRemoved = contents.flatMap(content => content?.gltf?.extensionsRemoved || []);
     if (extensionsRemoved.includes('KHR_draco_mesh_compression')) {
       this.contentFormats.draco = true;
     }
@@ -311,20 +664,133 @@ export class Tiles3DSource implements Tileset3DSource {
       this.contentFormats.ktx2 = true;
     }
 
-    if (loadResult.nestedTileset) {
-      tileset._initializeTileHeaders(loadResult.nestedTileset, tile);
+    const nestedTilesets =
+      loadResult.nestedTilesets || (loadResult.nestedTileset ? [loadResult.nestedTileset] : []);
+    const installedRoots = this.nestedTilesetRoots.get(tile) || [];
+    for (const [nestedIndex, nestedTileset] of nestedTilesets.entries()) {
+      const installedRoot = installedRoots[nestedIndex];
+      if (installedRoot && tile.children.includes(installedRoot)) {
+        continue;
+      }
+      const nextRoot = installedRoots
+        .slice(nestedIndex + 1)
+        .find(root => tile.children.includes(root));
+      const nestedRoot = tileset._initializeTileHeaders(
+        this.prepareNestedTileset(tileset, nestedTileset),
+        tile
+      );
+      // Header installation appends roots; restore declaration order before any later retained slot.
+      if (nextRoot) {
+        tile.children.splice(tile.children.indexOf(nestedRoot), 1);
+        tile.children.splice(tile.children.indexOf(nextRoot), 0, nestedRoot);
+      }
+      installedRoots[nestedIndex] = nestedRoot;
+      this.nestedTilesetRoots.set(tile, installedRoots);
     }
   }
 
+  /**
+   * Resolves a nested tileset's CRS independently and adapts it to the owning tileset output frame.
+   *
+   * Nested resources may use a different source CRS from their parent. Their headers and glTF
+   * payloads must therefore use a transformer built from the nested descriptor, while the parent
+   * runtime continues to expose one requested output frame to traversal and rendering.
+   */
+  private prepareNestedTileset(tileset: Tileset3D, nestedTileset: TilesetJSON): TilesetJSON {
+    const nestedSpatialReference = nestedTileset.spatialMetadata;
+    const parentSpatialReference = tileset.spatialReference;
+
+    if (
+      nestedSpatialReference?.status === 'unresolved' ||
+      nestedSpatialReference?.crs.state === 'unknown'
+    ) {
+      throw new Error(
+        nestedSpatialReference.warnings[0] ||
+          'Nested 3D Tiles CRS is explicitly unresolved and cannot be placed in the parent frame'
+      );
+    }
+
+    if (!nestedSpatialReference || !nestedSpatialReference.sourceCrs) {
+      if (
+        this.spatialTransformer &&
+        (parentSpatialReference.status === 'transformable' ||
+          parentSpatialReference.status === 'transformed')
+      ) {
+        return {
+          ...nestedTileset,
+          spatialMetadata: parentSpatialReference,
+          root: this.transformTileHeaderWithTransformer(
+            nestedTileset.root,
+            this.spatialTransformer,
+            new Matrix4(),
+            parentSpatialReference
+          )
+        };
+      }
+      return addNestedSpatialReference(nestedTileset, parentSpatialReference);
+    }
+
+    const parentCoordinateEpoch = parentSpatialReference.coordinateEpoch;
+    const nestedCoordinateEpoch = nestedSpatialReference.coordinateEpoch;
+    if (
+      parentCoordinateEpoch !== undefined &&
+      nestedCoordinateEpoch !== undefined &&
+      parentCoordinateEpoch !== nestedCoordinateEpoch
+    ) {
+      throw new Error(
+        `Nested 3D Tiles coordinate epoch ${nestedCoordinateEpoch} differs from parent epoch ${parentCoordinateEpoch}; epoch-aware transformation is unavailable`
+      );
+    }
+
+    const outputCrs = parentSpatialReference.targetCrs || parentSpatialReference.sourceCrs;
+    if (!outputCrs) {
+      return addNestedSpatialReference(nestedTileset, nestedSpatialReference);
+    }
+
+    const nestedOutputReference = applyTilesetSpatialOptions(nestedSpatialReference, {
+      ...tileset.options.spatial,
+      outputCoordinates: 'target-crs',
+      targetCrs: outputCrs
+    });
+    if (nestedOutputReference.status === 'unresolved') {
+      throw new Error(
+        nestedOutputReference.warnings[0] ||
+          'Nested 3D Tiles CRS cannot be resolved in the parent output frame'
+      );
+    }
+    if (nestedOutputReference.status === 'native') {
+      return addNestedSpatialReference(nestedTileset, nestedOutputReference);
+    }
+
+    const nestedTransformer = new Tiles3DSpatialTransformer(
+      nestedOutputReference,
+      tileset.options.spatial
+    );
+    return {
+      ...nestedTileset,
+      spatialMetadata: nestedOutputReference,
+      root: this.transformTileHeaderWithTransformer(
+        nestedTileset.root,
+        nestedTransformer,
+        new Matrix4(),
+        nestedOutputReference
+      )
+    };
+  }
+
   /**
    * Loads data through injected core APIs so this module stays independent from `@loaders.gl/core`.
    */
-  private async loadWithCoreApi(url: string, options: LoaderOptions): Promise<any> {
+  private async loadWithCoreApi(
+    url: string,
+    options: LoaderOptions,
+    loader: Loader = this.loader
+  ): Promise<any> {
     if (!this.coreApi) {
       throw new Error('Tiles3DSource requires an injected coreApi to load tileset data');
     }
 
-    return await this.coreApi.load(url, this.loader, options);
+    return await this.coreApi.load(url, loader, options);
   }
 
   /**
@@ -339,14 +805,177 @@ export class Tiles3DSource implements Tileset3DSource {
   }
 
   /**
-   * Loads tile content through an injected resolver when present, otherwise through the injected core API.
+   * Loads an arbitrary source resource through an injected resolver or core API.
    */
-  private async loadResourceData(url: string, options: LoaderOptions): Promise<any> {
+  private async loadResourceData(
+    url: string,
+    options: LoaderOptions,
+    loader: Loader = this.loader
+  ): Promise<any> {
     if (this.resolver) {
-      return await this.resolver.loadResource(url, this.loader, options);
+      return await this.resolver.loadResource(url, loader, options);
     }
 
-    return await this.loadWithCoreApi(url, options);
+    return await this.loadWithCoreApi(url, options, loader);
+  }
+
+  /** Loads a URL content reference or parses a buffer-view file retained from a glTF package. */
+  private async loadContentResource(
+    url: string,
+    packageResource: PackageResource | undefined,
+    options: LoaderOptions
+  ): Promise<any> {
+    if (!packageResource) {
+      return await this.loadResourceData(url, options);
+    }
+    const file = packageResource.files[packageResource.fileIndex];
+    if (!file) {
+      throw new Error(`3D Tiles package references missing file ${packageResource.fileIndex}`);
+    }
+    if (file.uri) {
+      return await this.loadResourceData(this.getTileUrl(file.uri), options);
+    }
+    if (!this.coreApi) {
+      throw new Error('Tiles3DSource requires an injected coreApi to parse embedded package data');
+    }
+
+    const data = await this.getPackageFileData(file);
+    const packageNamespace = this.getPackageNamespace(packageResource.files);
+    const packageRootUrl = `gltf-package://${packageNamespace}/${packageResource.fileIndex}`;
+    const fileName = file.name || 'content';
+    const directorySeparatorIndex = fileName.lastIndexOf('/');
+    const packageBaseUrl =
+      directorySeparatorIndex >= 0
+        ? `${packageRootUrl}/${fileName.slice(0, directorySeparatorIndex)}`
+        : packageRootUrl;
+    return await this.coreApi.parse(data, this.loader, options, {
+      url: `${packageRootUrl}/${fileName}`,
+      filename: fileName,
+      baseUrl: packageBaseUrl,
+      loaders: [this.loader],
+      coreApi: this.coreApi,
+      _parse: this.coreApi.parse,
+      _tiles3dPackageFiles: packageResource.files,
+      fetch: async (resource: string, init?: RequestInit) => {
+        const reference = resource.startsWith(`${packageRootUrl}/`)
+          ? resource.slice(packageRootUrl.length + 1)
+          : resource;
+        const referencedFile = packageResource.files.find(
+          packageFile => packageFile.name === reference || packageFile.originalUri === reference
+        );
+        if (!referencedFile) {
+          throw new Error(`3D Tiles glTF package does not contain file ${reference}`);
+        }
+        if (referencedFile.uri) {
+          return await this.coreApi!.fetchFile(this.getTileUrl(referencedFile.uri), init);
+        }
+        const referencedData = await this.getPackageFileData(referencedFile);
+        return new Response(referencedData, {
+          headers: {'content-type': referencedFile.mimeType}
+        });
+      }
+    } as Tiles3DPackageLoaderContext);
+  }
+
+  /** Returns a stable source-local namespace for one embedded glTF package file collection. */
+  private getPackageNamespace(files: PackageFile[]): number {
+    const existingNamespace = this.packageNamespaces.get(files);
+    if (existingNamespace !== undefined) {
+      return existingNamespace;
+    }
+    const packageNamespace = this.nextPackageNamespace++;
+    this.packageNamespaces.set(files, packageNamespace);
+    return packageNamespace;
+  }
+
+  /** Resolves a retained package-file byte range without eagerly copying other package files. */
+  private async getPackageFileData(file: PackageFile): Promise<ArrayBuffer> {
+    if (file.data) {
+      return sliceArrayBuffer(file.data, file.byteOffset, file.byteLength);
+    }
+    if (file.bufferUri && this.coreApi) {
+      const response = await this.coreApi.fetchFile(this.getTileUrl(file.bufferUri));
+      if (!response.ok) {
+        throw new Error(`Failed to fetch 3D Tiles package buffer: HTTP ${response.status}`);
+      }
+      const buffer = await response.arrayBuffer();
+      return sliceArrayBuffer(buffer, file.byteOffset, file.byteLength);
+    }
+    throw new Error('3D Tiles package file has no available byte source');
+  }
+
+  /**
+   * Returns a parsed subtree from the LRU cache or starts one source-managed request.
+   *
+   * @param subtreeUrl - Final subtree URL after query inheritance.
+   * @param packageResource - Optional glTF package file satisfying the subtree reference.
+   * @returns Parsed subtree availability data.
+   */
+  private async loadImplicitSubtreeResource(
+    subtreeUrl: string,
+    packageResource?: PackageResource
+  ): Promise<ParsedImplicitSubtree> {
+    const cachedSubtree = this.implicitSubtreeCache.get(subtreeUrl);
+    if (cachedSubtree) {
+      this.implicitTilingStats.cacheHits++;
+      return await cachedSubtree;
+    }
+
+    this.implicitTilingStats.requestedSubtrees++;
+    const loaderOptions = (this.loadOptions[this.loader.id] as Record<string, unknown>) || {};
+    return await this.implicitSubtreeCache.getOrLoad(subtreeUrl, async () => {
+      const options = {
+        ...this.loadOptions,
+        [this.loader.id]: {
+          ...loaderOptions,
+          isTileset: false,
+          isSubtree: true
+        }
+      };
+      return (await (packageResource
+        ? this.loadContentResource(subtreeUrl, packageResource, options)
+        : this.loadResourceData(subtreeUrl, options))) as ParsedImplicitSubtree;
+    });
+  }
+
+  /**
+   * Instantiates every header represented by one materialized subtree.
+   *
+   * @param tileset - Owning runtime tileset.
+   * @param parentTile - Existing materialized parent.
+   * @param childHeaders - Headers to install below the parent.
+   * @returns Number of newly allocated runtime tile nodes.
+   */
+  private initializeMaterializedChildren(
+    tileset: Tileset3D,
+    parentTile: Tile3D,
+    childHeaders: Record<string, any>[]
+  ): number {
+    let materializedTileCount = 0;
+    const stack: Array<{parentTile: Tile3D; childHeaders: Record<string, any>[]}> = [
+      {parentTile, childHeaders}
+    ];
+    while (stack.length > 0) {
+      const entry = stack.pop()!;
+      for (const childHeader of entry.childHeaders) {
+        const childTile = new Tile3DNode(tileset, childHeader, entry.parentTile);
+        entry.parentTile.children.push(childTile);
+        childTile.depth = entry.parentTile.depth + 1;
+        tileset.stats.get('Tiles In Tileset(s)').incrementCount();
+        materializedTileCount++;
+        if (childHeader.children?.length) {
+          stack.push({parentTile: childTile, childHeaders: childHeader.children});
+        }
+      }
+    }
+    return materializedTileCount;
+  }
+}
+
+/** Throws a cancellation reason before or after source-managed traversal work. */
+function throwIfTraversalAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
   }
 }
 
@@ -377,3 +1006,20 @@ function normalizeTiles3DRequest(input: TilesetSourceInput): TilesetSourceReques
     coreApi: (input as TilesetSourceRequest).coreApi
   };
 }
+
+/** Adds a nested CRS descriptor to each header without changing its native placement. */
+function addNestedSpatialReference(
+  nestedTileset: TilesetJSON,
+  spatialReference: TilesetSpatialReference
+): TilesetJSON {
+  const addToHeader = (header: Record<string, any>): Record<string, any> => ({
+    ...header,
+    _spatialReference: spatialReference,
+    children: Array.isArray(header.children) ? header.children.map(addToHeader) : header.children
+  });
+  return {
+    ...nestedTileset,
+    spatialMetadata: spatialReference,
+    root: addToHeader(nestedTileset.root)
+  };
+}