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

package/src/spatial/spatial-resource-registry.ts

@@ -3,22 +3,22 @@
 // Copyright (c) vis.gl contributors
 
 import {Geoid, parsePGM} from '@math.gl/geoid';
-import {Proj4Projection} from '@math.gl/proj4';
-import type {Proj4CRSDefinition} from '@math.gl/proj4';
+import {Projection} from '@math.gl/projection';
+import type {ReadonlyCRSDefinition} from '@math.gl/crs';
 
 const geoidModels = new Map<string, Geoid>();
 
 /**
- * Registers an application-supplied CRS alias for deterministic Proj4 transformations.
+ * Registers an application-supplied CRS alias for deterministic coordinate transformations.
  *
  * loaders.gl never downloads registry definitions implicitly.
  *
  * @param name - Identifier used by dataset metadata or application options.
- * @param definition - CRS definition understood by `@math.gl/proj4`.
+ * @param definition - CRS definition understood by `@math.gl/projection`.
  */
-export function registerSpatialCrs(name: string, definition: Proj4CRSDefinition): void {
+export function registerSpatialCrs(name: string, definition: ReadonlyCRSDefinition): void {
   validateResourceName(name, 'CRS');
-  Proj4Projection.defineProjectionAliases({[name]: definition});
+  Projection.defineProjectionAliases({[name]: definition});
 }
 
 /**
@@ -29,7 +29,7 @@ export function registerSpatialCrs(name: string, definition: Proj4CRSDefinition)
  */
 export function registerSpatialDatumGrid(name: string, data: ArrayBuffer): void {
   validateResourceName(name, 'datum grid');
-  Proj4Projection.registerDatumGrid(name, data);
+  Projection.registerDatumGrid(name, data);
 }
 
 /**

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

@@ -602,23 +602,7 @@ export class Tile3D {
     }
 
     try {
-      const loadResult = await this.tileset.source.loadTileContent(this);
-
-      if (loadResult.contents) {
-        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);
-      }
-
-      this.contentState = TILE_CONTENT_STATE.READY;
-      this._onContentLoaded();
-      this._updateContentEntriesAfterLoad(loadResult);
-      return loadResult;
+      return await this._loadContentFromSource();
     } catch (error) {
       // Tile is unloaded before the content finishes loading
       this.contentState = TILE_CONTENT_STATE.FAILED;
@@ -628,6 +612,44 @@ export class Tile3D {
     }
   }
 
+  /** Loads content for complete dataset operations without viewport-based request priority. */
+  async loadContentForTraversal(): Promise<TileContentLoadResult> {
+    if (this.hasEmptyContent) {
+      return {loaded: false};
+    }
+    if (this.content) {
+      return {loaded: true, contents: this.contents};
+    }
+
+    this.contentState = TILE_CONTENT_STATE.LOADING;
+    try {
+      return await this._loadContentFromSource();
+    } catch (error) {
+      this.contentState = TILE_CONTENT_STATE.FAILED;
+      throw error;
+    }
+  }
+
+  /** Loads source content and updates the tile's renderer-neutral payload state. */
+  private async _loadContentFromSource(): Promise<TileContentLoadResult> {
+    const loadResult = await this.tileset.source.loadTileContent(this);
+    if (loadResult.contents) {
+      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);
+    }
+
+    this.contentState = TILE_CONTENT_STATE.READY;
+    this._onContentLoaded();
+    this._updateContentEntriesAfterLoad(loadResult);
+    return loadResult;
+  }
+
   /**
    * Requests and installs this tile's lazy child-header group through its source.
    *

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

@@ -58,17 +58,6 @@ export type Tileset3DProps = {
    * @default 536870912
    */
   maximumCacheOverflowBytes?: number;
-  /**
-   * Soft cache target in mebibytes.
-   * @deprecated Use {@link Tileset3DProps.cacheBytes}; when both are supplied, `cacheBytes` wins.
-   */
-  maximumMemoryUsage?: number;
-  /**
-   * Cache overflow headroom in mebibytes.
-   * @deprecated Use {@link Tileset3DProps.maximumCacheOverflowBytes}; when both are supplied, the
-   * byte-native option wins.
-   */
-  memoryCacheOverflow?: number;
   maximumTilesSelected?: number;
   debounceTime?: number;
 
@@ -158,10 +147,6 @@ type Props = {
   cacheBytes: number;
   /** Current-frame headroom, in bytes, before memory-adjusted SSE rises. */
   maximumCacheOverflowBytes: number;
-  /** @deprecated Byte-native code should use `cacheBytes`. */
-  maximumMemoryUsage: number;
-  /** @deprecated Byte-native code should use `maximumCacheOverflowBytes`. */
-  memoryCacheOverflow: number;
   maximumTilesSelected: number;
   debounceTime: number;
   onTileLoad: (tile: Tile3D) => void;
@@ -241,31 +226,21 @@ function validateCacheByteLength(value: number, optionName: string): number {
 }
 
 /**
- * Resolves the base cache target from byte-native or deprecated mebibyte options.
+ * Resolves the base cache target from the byte-native option or its fallback.
  *
- * The byte-native option takes precedence so mixed migration configurations are deterministic.
- * The fallback is already expressed in bytes and is used for both construction and runtime updates.
- *
- * @param options - Options that may contain byte-native or deprecated cache values.
+ * @param options - Options that may contain a byte-native cache value.
  * @param fallbackCacheBytes - Existing or default cache target in bytes.
  * @returns The resolved and validated cache target in bytes.
  */
 function resolveCacheBytes(options: Tileset3DProps, fallbackCacheBytes: number): number {
-  const cacheBytes =
-    options.cacheBytes ??
-    (options.maximumMemoryUsage !== undefined
-      ? options.maximumMemoryUsage * BYTES_PER_MEBIBYTE
-      : fallbackCacheBytes);
+  const cacheBytes = options.cacheBytes ?? fallbackCacheBytes;
   return validateCacheByteLength(cacheBytes, 'cacheBytes');
 }
 
 /**
- * Resolves cache overflow headroom from byte-native or deprecated mebibyte options.
- *
- * The byte-native option takes precedence so callers can migrate the two cache controls
- * independently without unit ambiguity.
+ * Resolves cache overflow headroom from the byte-native option or its fallback.
  *
- * @param options - Options that may contain byte-native or deprecated overflow values.
+ * @param options - Options that may contain a byte-native overflow value.
  * @param fallbackOverflowBytes - Existing or default overflow headroom in bytes.
  * @returns The resolved and validated overflow headroom in bytes.
  */
@@ -273,11 +248,7 @@ function resolveMaximumCacheOverflowBytes(
   options: Tileset3DProps,
   fallbackOverflowBytes: number
 ): number {
-  const maximumCacheOverflowBytes =
-    options.maximumCacheOverflowBytes ??
-    (options.memoryCacheOverflow !== undefined
-      ? options.memoryCacheOverflow * BYTES_PER_MEBIBYTE
-      : fallbackOverflowBytes);
+  const maximumCacheOverflowBytes = options.maximumCacheOverflowBytes ?? fallbackOverflowBytes;
   return validateCacheByteLength(maximumCacheOverflowBytes, 'maximumCacheOverflowBytes');
 }
 
@@ -289,8 +260,6 @@ const DEFAULT_PROPS: Props = {
   maxRequests: 64,
   cacheBytes: DEFAULT_CACHE_BYTES,
   maximumCacheOverflowBytes: DEFAULT_MAXIMUM_CACHE_OVERFLOW_BYTES,
-  maximumMemoryUsage: DEFAULT_CACHE_BYTES / BYTES_PER_MEBIBYTE,
-  memoryCacheOverflow: DEFAULT_MAXIMUM_CACHE_OVERFLOW_BYTES / BYTES_PER_MEBIBYTE,
   maximumTilesSelected: 0,
   debounceTime: 0,
   onTileLoad: () => {},
@@ -456,8 +425,6 @@ export class Tileset3D {
       ...suppliedOptions,
       cacheBytes,
       maximumCacheOverflowBytes,
-      maximumMemoryUsage: cacheBytes / BYTES_PER_MEBIBYTE,
-      memoryCacheOverflow: maximumCacheOverflowBytes / BYTES_PER_MEBIBYTE,
       memoryAdjustedScreenSpaceError:
         suppliedOptions.memoryAdjustedScreenSpaceError ?? usesTiles3DCacheDefaults
     };
@@ -552,7 +519,6 @@ export class Tileset3D {
   set cacheBytes(value: number) {
     this._cacheBytes = validateCacheByteLength(value, 'cacheBytes');
     this.options.cacheBytes = this._cacheBytes;
-    this.options.maximumMemoryUsage = this._cacheBytes / BYTES_PER_MEBIBYTE;
   }
 
   /**
@@ -569,19 +535,6 @@ export class Tileset3D {
   set maximumCacheOverflowBytes(value: number) {
     this._maximumCacheOverflowBytes = validateCacheByteLength(value, 'maximumCacheOverflowBytes');
     this.options.maximumCacheOverflowBytes = this._maximumCacheOverflowBytes;
-    this.options.memoryCacheOverflow = this._maximumCacheOverflowBytes / BYTES_PER_MEBIBYTE;
-  }
-
-  /**
-   * Gets or sets the soft cache target in mebibytes.
-   * @deprecated Use {@link Tileset3D.cacheBytes}. Assignments remain synchronized for compatibility.
-   */
-  get maximumMemoryUsage(): number {
-    return this.cacheBytes / BYTES_PER_MEBIBYTE;
-  }
-
-  set maximumMemoryUsage(value: number) {
-    this.cacheBytes = validateCacheByteLength(value * BYTES_PER_MEBIBYTE, 'maximumMemoryUsage');
   }
 
   get queryParams(): string {
@@ -591,10 +544,7 @@ export class Tileset3D {
   }
 
   /**
-   * Updates traversal and runtime options, synchronizing byte-native and deprecated cache values.
-   *
-   * For each budget, the byte-native option takes precedence when both unit forms are supplied.
-   * Unspecified budgets retain their current byte values, avoiding repeated MiB conversion.
+   * Updates traversal and runtime options while retaining unspecified byte budgets.
    *
    * @param props - Partial runtime options to apply.
    */
@@ -608,9 +558,7 @@ export class Tileset3D {
       ...this.options,
       ...props,
       cacheBytes,
-      maximumCacheOverflowBytes,
-      maximumMemoryUsage: cacheBytes / BYTES_PER_MEBIBYTE,
-      memoryCacheOverflow: maximumCacheOverflowBytes / BYTES_PER_MEBIBYTE
+      maximumCacheOverflowBytes
     };
     this._cacheBytes = cacheBytes;
     this._maximumCacheOverflowBytes = maximumCacheOverflowBytes;

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

@@ -0,0 +1,114 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Tile3D} from './tile-3d';
+import type {Tileset3D} from './tileset-3d';
+import type {TileContentLoadResult} from './tileset-source';
+import type {Tile3DContent} from './tile-3d-contracts';
+import {TILESET_TYPE} from '../../constants';
+
+/** Options for complete camera-independent tileset content traversal. */
+export interface TraverseTilesetContentsOptions {
+  /** Cancel traversal and stop issuing further source requests. */
+  readonly signal?: AbortSignal;
+  /**
+   * Unload content loaded by this traversal when iteration advances or closes, including on error.
+   * Defaults to false. Preloaded content is retained. Use a runtime dedicated to this traversal;
+   * consume payloads before advancing and do not retain them or update the runtime concurrently.
+   */
+  readonly unloadContent?: boolean;
+}
+
+/** One tile placement and its ordered content entries from a completed source read. */
+export interface TilesetContentTraversalItem {
+  /** Runtime tile placement. Shared content resources are yielded once per placement. */
+  readonly tile: Tile3D;
+  /** Ordered content entries, including multiple contents declared by a single tile. */
+  readonly contents: readonly Tile3DContent[];
+}
+
+/**
+ * Walks every declared tile placement and its loaded content without a camera or visibility test.
+ *
+ * Source implementations remain responsible for lazy subtree and node-page resolution. Children
+ * are visited in declaration order, nested tilesets are installed by the source before descent,
+ * and repeated resource URLs are not deduplicated because each placement can have a distinct
+ * transform. Content stays attached unless `unloadContent` is enabled. In that mode, newly loaded
+ * payloads are valid until iteration advances or closes. Tile placements and children remain
+ * available; callers still own the tileset, source, and archive lifetime.
+ *
+ * @param tileset - Initialized or initializing source-backed tileset runtime.
+ * @param options - Cancellation and decoded-content lifetime options.
+ * @returns One item for each visited tile placement in deterministic depth-first order.
+ */
+export async function* traverseTilesetContents(
+  tileset: Tileset3D,
+  options: TraverseTilesetContentsOptions = {}
+): AsyncGenerator<TilesetContentTraversalItem> {
+  await tileset.tilesetInitializationPromise;
+  throwIfAborted(options.signal);
+  if (!tileset.root) {
+    throw new Error('Tileset initialization completed without a root tile');
+  }
+
+  const stack: Tile3D[] = [tileset.root];
+  const visitedTiles = new Set<Tile3D>();
+  while (stack.length > 0) {
+    throwIfAborted(options.signal);
+    const tile = stack.pop() as Tile3D;
+    if (visitedTiles.has(tile)) {
+      continue;
+    }
+    visitedTiles.add(tile);
+
+    if (tile.header.implicitSubtree && tile.childrenState !== 'ready') {
+      const loadChildren = tileset.source.loadTileChildrenForTraversal;
+      if (!loadChildren) {
+        throw new Error('Tileset source does not support camera-independent subtree loading');
+      }
+      const result = await loadChildren.call(tileset.source, tile, options.signal);
+      if (!result.loaded) {
+        throw new Error(`Unable to load implicit subtree for tile ${tile.id}`);
+      }
+      tile.childrenState = 'ready';
+    }
+
+    if (tileset.type === TILESET_TYPE.I3S && tileset.source.loadTileChildrenForTraversal) {
+      const result = await tileset.source.loadTileChildrenForTraversal(tile, options.signal);
+      if (!result.loaded) {
+        throw new Error(`Unable to load I3S child nodes for tile ${tile.id}`);
+      }
+    }
+
+    throwIfAborted(options.signal);
+    const loadsContent = tile.contentUrls.length > 0 && !tile.content;
+    try {
+      if (loadsContent) {
+        const loadResult: TileContentLoadResult = await tile.loadContentForTraversal();
+        throwIfAborted(options.signal);
+        if (!loadResult.loaded) {
+          throw new Error(`Unable to load tile content for tile ${tile.id}`);
+        }
+        tileset.source.onTileLoaded?.(tileset, tile, loadResult);
+      }
+
+      yield {tile, contents: tile.contentEntries};
+    } finally {
+      if (options.unloadContent && loadsContent) {
+        tile.unloadContent();
+      }
+    }
+
+    for (let childIndex = tile.children.length - 1; childIndex >= 0; childIndex--) {
+      stack.push(tile.children[childIndex]);
+    }
+  }
+}
+
+/** Throws the signal reason when traversal is cancelled. */
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+  }
+}

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

@@ -221,6 +221,17 @@ export interface Tileset3DSource {
    */
   loadTileChildren?(tile: Tile3D, frameState: FrameState): Promise<TileChildrenLoadResult>;
 
+  /**
+   * Loads all source-managed child headers without requiring camera or visibility state.
+   *
+   * This hook is used by complete dataset operations such as conversion. Implementations retain
+   * ownership of implicit subtrees, node pages, archive resolution, and query inheritance.
+   */
+  loadTileChildrenForTraversal?(
+    tile: Tile3D,
+    signal?: AbortSignal
+  ): Promise<TileChildrenLoadResult>;
+
   /**
    * Resolves a tile-relative path to the final request URL.
    */
@@ -239,7 +250,11 @@ export interface Tileset3DSource {
   /**
    * Loads child tile metadata on demand for formats that do not expose the full tree up front.
    */
-  loadChildTileHeader?(parentTile: Tile3D, childId: string, frameState: FrameState): Promise<any>;
+  loadChildTileHeader?(
+    parentTile: Tile3D,
+    childId: string,
+    frameState: FrameState | null
+  ): Promise<any>;
 
   /**
    * Updates source-managed bookkeeping after a tile finishes loading.

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

@@ -119,6 +119,8 @@ export class Tiles3DSource implements Tileset3DSource {
   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. */
@@ -521,6 +523,17 @@ export class Tiles3DSource implements Tileset3DSource {
     };
   }
 
+  /** 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.
    *
@@ -634,7 +647,9 @@ 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 contents = tile.contents.length ? tile.contents : [tile.content];
@@ -651,8 +666,26 @@ export class Tiles3DSource implements Tileset3DSource {
 
     const nestedTilesets =
       loadResult.nestedTilesets || (loadResult.nestedTileset ? [loadResult.nestedTileset] : []);
-    for (const nestedTileset of nestedTilesets) {
-      tileset._initializeTileHeaders(this.prepareNestedTileset(tileset, nestedTileset), tile);
+    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);
     }
   }
 
@@ -939,6 +972,13 @@ export class Tiles3DSource implements Tileset3DSource {
   }
 }
 
+/** 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');
+  }
+}
+
 function isTilesetRequest(input: TilesetSourceInput): input is TilesetSourceRequest {
   return Boolean(
     input && typeof input === 'object' && 'url' in input && 'loader' in input && !('type' in input)

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

@@ -8,10 +8,12 @@ import {Vector3} from '@math.gl/core';
 import type {CoreAPI, Loader, LoaderOptions} from '@loaders.gl/loader-utils';
 import type {Tile3D} from '../common/tile-3d';
 import {Tile3D as Tile3DNode} from '../common/tile-3d';
+import type {Tile3DContent} from '../common/tile-3d-contracts';
 import {I3STilesetTraverser} from './i3s-tileset-traverser';
 import type {Tileset3D} from '../common/tileset-3d';
 import type {FrameState} from '../helpers/frame-state';
 import type {
+  TileChildrenLoadResult,
   TileContentLoadResult,
   TilesetContentFormats,
   TilesetJSON,
@@ -219,7 +221,17 @@ export class I3SSource implements Tileset3DSource {
     };
 
     tile.content = await this.loadResourceData(contentUrl, options, this.contentLoader);
-    return {loaded: true};
+    const contentEntry: Tile3DContent = {
+      index: 0,
+      uri: tile.contentUrl,
+      type: tile.header.layerType,
+      payload: tile.content,
+      metadata: tile.header.metadata || null,
+      boundingVolume: tile.boundingVolume,
+      featureIds: tile.featureIdSets,
+      renderable: Boolean(tile.content)
+    };
+    return {loaded: true, contents: [tile.content], contentEntries: [contentEntry]};
   }
 
   /**
@@ -228,7 +240,7 @@ export class I3SSource implements Tileset3DSource {
   async loadChildTileHeader(
     _parentTile: Tile3D,
     childId: string,
-    _frameState: FrameState
+    _frameState: FrameState | null
   ): Promise<any> {
     const metadata = this.getMetadata();
     if (metadata.tileset.nodePages || metadata.tileset.pointNodePages) {
@@ -253,6 +265,50 @@ export class I3SSource implements Tileset3DSource {
     return await this.transformTileHeader(header);
   }
 
+  /** Loads all declared I3S child headers without camera or visibility state. */
+  async loadTileChildrenForTraversal(
+    parentTile: Tile3D,
+    signal?: AbortSignal
+  ): Promise<TileChildrenLoadResult> {
+    const childHeaders = parentTile.header.children || [];
+    let loadedChildren = 0;
+    const orderedChildren: Tile3D[] = [];
+
+    for (const childHeader of childHeaders) {
+      throwIfTraversalAborted(signal);
+      const childId = childHeader.id;
+      if (typeof childId !== 'string' && typeof childId !== 'number') {
+        throw new Error('I3S child header is missing its node ID');
+      }
+      const existingChild = parentTile.children.find(
+        tile => tile.id === String(childId) || tile.header?.id === childId
+      );
+      if (existingChild) {
+        orderedChildren.push(existingChild);
+        continue;
+      }
+
+      const childTileHeader = await this.loadChildTileHeader(parentTile, String(childId), null);
+      throwIfTraversalAborted(signal);
+      const childTile = new Tile3DNode(
+        parentTile.tileset,
+        childTileHeader,
+        parentTile,
+        String(childId)
+      );
+      orderedChildren.push(childTile);
+      loadedChildren++;
+    }
+
+    const orderedChildSet = new Set(orderedChildren);
+    parentTile.children = [
+      ...orderedChildren,
+      ...parentTile.children.filter(childTile => !orderedChildSet.has(childTile))
+    ];
+
+    return {loaded: true, tileCount: loadedChildren, childSubtreeCount: 0};
+  }
+
   /**
    * Resolves an I3S request URL with source-managed query parameters.
    */
@@ -265,24 +321,28 @@ export class I3SSource implements Tileset3DSource {
       return tilePath;
     }
 
-    const queryDelimiterIndex = tilePath.indexOf('?');
-    if (queryDelimiterIndex === -1) {
-      return `${tilePath}?${new URLSearchParams(this.queryParams).toString()}`;
-    }
-
-    const existingQuery = tilePath.slice(queryDelimiterIndex + 1);
-    const existingQueryKeys = new Set(
-      existingQuery.split('&').map(parameter => parameter.split('=', 1)[0])
-    );
+    const hashIndex = tilePath.indexOf('#');
+    const hash = hashIndex >= 0 ? tilePath.slice(hashIndex) : '';
+    const tilePathWithoutHash = hashIndex >= 0 ? tilePath.slice(0, hashIndex) : tilePath;
+    const queryDelimiterIndex = tilePathWithoutHash.indexOf('?');
+    const path =
+      queryDelimiterIndex === -1
+        ? tilePathWithoutHash
+        : tilePathWithoutHash.slice(0, queryDelimiterIndex);
+    const existingQuery =
+      queryDelimiterIndex === -1 ? '' : tilePathWithoutHash.slice(queryDelimiterIndex + 1);
+    const existingQueryParams = new URLSearchParams(existingQuery);
     const queryParams = new URLSearchParams();
     for (const [key, value] of Object.entries(this.queryParams)) {
-      if (!existingQueryKeys.has(key)) {
+      if (!existingQueryParams.has(key)) {
         queryParams.set(key, value);
       }
     }
 
     const queryString = queryParams.toString();
-    return queryString ? `${tilePath}${existingQuery ? '&' : ''}${queryString}` : tilePath;
+    return `${path}${existingQuery ? `?${existingQuery}` : ''}${
+      queryString ? `${existingQuery ? '&' : '?'}${queryString}` : ''
+    }${hash}`;
   }
 
   /**
@@ -403,6 +463,10 @@ export class I3SSource implements Tileset3DSource {
    * @param loadOptions Loader options that may contain an ArcGIS token.
    */
   private initializeQueryParams(loadOptions: LoaderOptions): void {
+    for (const [key, value] of Object.entries(loadOptions.searchParams || {})) {
+      this.queryParams[key] = String(value);
+    }
+
     const i3sOptions = loadOptions.i3s;
     if (i3sOptions && typeof i3sOptions === 'object' && 'token' in i3sOptions) {
       const token = (i3sOptions as Record<string, unknown>).token;
@@ -449,6 +513,13 @@ export class I3SSource implements Tileset3DSource {
   }
 }
 
+/** 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');
+  }
+}
+
 /** Returns the format-provided binary content loader, falling back for custom legacy loaders. */
 function getI3SContentLoader(loader: Loader): Loader {
   return (loader as Loader & {contentLoader?: Loader}).contentLoader || loader;

package/src/tileset-3d/format-i3s/i3s-tileset-traverser.ts

@@ -38,7 +38,8 @@ export class I3STilesetTraverser extends TilesetTraverser {
     for (const child of children) {
       const extendedId = `${child.id}-${frameState.viewport.id}`;
       // if child tile is not fetched
-      const childTile = childTiles && childTiles.find(t => t.id === extendedId);
+      const childTile =
+        childTiles && childTiles.find(t => t.id === extendedId || t.header?.id === child.id);
       if (!childTile) {
         const request = () => this._loadTile(tile, child.id, frameState);
         const cachedRequest = this._tileManager.find(extendedId);