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

package/dist/tileset-3d/format-3d-tiles/tiles-3d-source.js

@@ -1,19 +1,24 @@
 // loaders.gl
 // 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 { Matrix4, Vector3 } from '@math.gl/core';
 import { Tileset3DTraverser } from "./tileset-3d-traverser.js";
 import { Tile3D as Tile3DNode } from "../common/tile-3d.js";
 import { getZoomFromBoundingVolume } from "../helpers/zoom.js";
 import { TILESET_TYPE } from "../../constants.js";
+import { get3DTilesSpatialReference } from "../../spatial/format-spatial-reference.js";
+import { Tiles3DSpatialTransformer } from "../../spatial/tiles-3d-spatial-transformer.js";
+import { applyTilesetSpatialOptions, markTilesetSpatialReferenceTransformed } from "../../spatial/spatial-types.js";
+import { materializeImplicitSubtree } from "./implicit-tiling.js";
 const EMPTY_CONTENT_FORMATS = {
     draco: false,
     meshopt: false,
     dds: false,
     ktx2: false
 };
+const DEFAULT_MAXIMUM_CACHED_SUBTREES = 32;
 /**
  * {@link Tileset3DSource} implementation for 3D Tiles datasets.
  */
@@ -45,9 +50,34 @@ export class Tiles3DSource {
     /** Normalized source metadata after initialization. */
     metadata;
     queryParams = {};
+    /** Final request URLs cached by unmodified tile content URL. */
+    tileUrlCache = new Map();
+    /** Original content descriptors retained across {@link Tile3D.unloadContent} calls. */
+    tileContentHeaders = new WeakMap();
+    /** Installed nested roots by parent placement and ordered nested-content slot, across reloads. */
+    nestedTilesetRoots = new WeakMap();
+    /** Source-local namespaces assigned to distinct embedded glTF package file collections. */
+    packageNamespaces = new WeakMap();
+    /** Next source-local package namespace. */
+    nextPackageNamespace = 0;
+    /** Parsed subtree requests keyed by final source URL for deduplication and LRU reuse. */
+    implicitSubtreeCache;
+    /** Mutable counters exposed as a defensive snapshot through {@link getImplicitTilingStats}. */
+    implicitTilingStats = {
+        requestedSubtrees: 0,
+        loadedSubtrees: 0,
+        cacheHits: 0,
+        materializedTiles: 0
+    };
+    /** Whether the owning tileset has released this source. */
+    destroyed = false;
     extensionsUsed = [];
     resolver;
     rootTileset;
+    /** CRS transformer shared by this source's headers and decoded glTF content. */
+    spatialTransformer;
+    /** Root header after composing source-frame transforms and rebuilding target bounds. */
+    preparedRootHeader;
     /**
      * Creates a 3D Tiles source.
      * @param input Root metadata request, or preloaded root metadata for tests and internal callers.
@@ -63,6 +93,22 @@ export class Tiles3DSource {
         this.resolver = request.resolver;
         this.coreApi = request.coreApi;
         this.loadOptions = loadOptions;
+        const maximumCachedSubtrees = Number(loadOptions['3d-tiles']?.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() {
+        this.destroyed = true;
+        this.tileUrlCache.clear();
+        this.implicitSubtreeCache.clear();
     }
     /**
      * Fetches and validates top-level metadata, then normalizes common fields used by {@link Tileset3D}.
@@ -81,19 +127,22 @@ export class Tiles3DSource {
         this.tileset = this.rootTileset;
         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;
         if (!this.asset) {
             throw new Error('Tileset must have an asset property.');
         }
-        if (this.asset.version !== '0.0' &&
+        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;
         this.extras = this.rootTileset.extras;
@@ -107,7 +156,8 @@ export class Tiles3DSource {
             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)
         };
     }
     /**
@@ -125,11 +175,26 @@ export class Tiles3DSource {
     async getRootTileset() {
         return this.getMetadata().tileset;
     }
+    /** Prepare nonlinear CRS state before runtime headers are materialized. */
+    async prepareTileset(tileset) {
+        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, tilesetJson, parentTile) {
-        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);
             rootTile.depth = parentTile.depth + 1;
@@ -145,7 +210,7 @@ export class Tiles3DSource {
                     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);
@@ -165,31 +230,179 @@ export class Tiles3DSource {
      * Loads binary content or nested tileset JSON for a runtime tile.
      */
     async loadTileContent(tile) {
-        const contentUrl = this.getTileUrl(tile.contentUrl);
+        const contentUrls = (tile.contentUrls || [tile.contentUrl]).filter(Boolean);
+        const cachedContentHeaders = this.tileContentHeaders.get(tile);
+        const contentHeaders = 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] || {};
         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],
+                        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. */
+    transformTileHeader(header, parentTransform = new Matrix4()) {
+        if (!this.spatialTransformer) {
+            return header;
+        }
+        return this.transformTileHeaderWithTransformer(header, this.spatialTransformer, parentTransform);
+    }
+    /** Rebuilds one header subtree using an explicitly selected CRS transformer. */
+    transformTileHeaderWithTransformer(header, transformer, parentTransform, spatialReference) {
+        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) => 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) => this.transformTileHeaderWithTransformer(child, transformer, composedTransform, spatialReference))
+                : header.children
+        };
+    }
+    transformContentHeader(content, composedTransform, transformer) {
+        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, frameState) {
+        void frameState;
+        const reference = tile.header.implicitSubtree;
+        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;
+        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, signal) {
+        throwIfTraversalAborted(signal);
+        const result = await this.loadTileChildren(tile, {});
+        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() {
+        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) {
         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;
         }
         const [pathWithoutQuery, existingQuery = ''] = tilePath.split('?');
@@ -200,7 +413,26 @@ export class Tiles3DSource {
             }
         }
         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.
+     */
+    setQueryParameter(parameterName, parameterValue) {
+        if (this.queryParams[parameterName] === parameterValue) {
+            return;
+        }
+        this.queryParams[parameterName] = parameterValue;
+        this.tileUrlCache.clear();
     }
     /**
      * Derives the default view state from the root bounding volume.
@@ -241,10 +473,13 @@ export class Tiles3DSource {
         return this.extensionsUsed.includes(extensionName);
     }
     /**
-     * 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, tile, loadResult) {
-        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;
         }
@@ -254,18 +489,91 @@ export class Tiles3DSource {
         if (extensionsRemoved.includes('KHR_texture_basisu')) {
             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.
+     */
+    prepareNestedTileset(tileset, nestedTileset) {
+        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`.
      */
-    async loadWithCoreApi(url, options) {
+    async loadWithCoreApi(url, options, loader = this.loader) {
         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);
     }
     /**
      * Loads data through an injected resolver when present, otherwise through the injected core API.
@@ -277,13 +585,150 @@ export class Tiles3DSource {
         return await this.loadWithCoreApi(url, options);
     }
     /**
-     * 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.
      */
-    async loadResourceData(url, options) {
+    async loadResourceData(url, options, loader = this.loader) {
         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. */
+    async loadContentResource(url, packageResource, options) {
+        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, init) => {
+                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 }
+                });
+            }
+        });
+    }
+    /** Returns a stable source-local namespace for one embedded glTF package file collection. */
+    getPackageNamespace(files) {
+        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. */
+    async getPackageFileData(file) {
+        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.
+     */
+    async loadImplicitSubtreeResource(subtreeUrl, packageResource) {
+        const cachedSubtree = this.implicitSubtreeCache.get(subtreeUrl);
+        if (cachedSubtree) {
+            this.implicitTilingStats.cacheHits++;
+            return await cachedSubtree;
+        }
+        this.implicitTilingStats.requestedSubtrees++;
+        const loaderOptions = this.loadOptions[this.loader.id] || {};
+        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)));
+        });
+    }
+    /**
+     * 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.
+     */
+    initializeMaterializedChildren(tileset, parentTile, childHeaders) {
+        let materializedTileCount = 0;
+        const stack = [
+            { 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) {
+    if (signal?.aborted) {
+        throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
     }
 }
 function isTilesetRequest(input) {
@@ -309,4 +754,17 @@ function normalizeTiles3DRequest(input) {
         coreApi: input.coreApi
     };
 }
+/** Adds a nested CRS descriptor to each header without changing its native placement. */
+function addNestedSpatialReference(nestedTileset, spatialReference) {
+    const addToHeader = (header) => ({
+        ...header,
+        _spatialReference: spatialReference,
+        children: Array.isArray(header.children) ? header.children.map(addToHeader) : header.children
+    });
+    return {
+        ...nestedTileset,
+        spatialMetadata: spatialReference,
+        root: addToHeader(nestedTileset.root)
+    };
+}
 //# sourceMappingURL=tiles-3d-source.js.map