@loaders.gl/tile-converter 5.0.0-alpha.11 → 5.0.0-alpha.14

package/dist/v5/core.js

@@ -27,9 +27,23 @@ async function convertTileset(options) {
     measureOutputBytes,
     maxInputResourceBytes = Number.POSITIVE_INFINITY,
     maxOutputResourceBytes = Number.POSITIVE_INFINITY,
+    maxInputBytes = Number.POSITIVE_INFINITY,
+    maxOutputBytes = Number.POSITIVE_INFINITY,
+    maxInputResources = Number.POSITIVE_INFINITY,
+    maxOutputResources = Number.POSITIVE_INFINITY,
     signal,
     onProgress
   } = options;
+  const started = options.profile ? performance.now() : 0;
+  const timings = options.profile ? {
+    inspectMilliseconds: 0,
+    readMilliseconds: 0,
+    convertMilliseconds: 0,
+    validateMilliseconds: 0,
+    writeMilliseconds: 0,
+    finalizeMilliseconds: 0,
+    totalMilliseconds: 0
+  } : void 0;
   let inputResources = 0;
   let outputResources = 0;
   let inputBytes = 0;
@@ -40,16 +54,34 @@ async function convertTileset(options) {
     onProgress?.({ phase, inputResources, outputResources, inputBytes, outputBytes });
   };
   try {
-    if (maxInputResourceBytes !== Number.POSITIVE_INFINITY && (!Number.isSafeInteger(maxInputResourceBytes) || maxInputResourceBytes < 0)) {
-      throw new TileConversionError(
-        "INVALID_INPUT_RESOURCE_LIMIT",
-        "maxInputResourceBytes must be a nonnegative safe integer or Infinity"
-      );
+    for (const [name, limit, code] of [
+      ["maxInputResourceBytes", maxInputResourceBytes, "INVALID_INPUT_RESOURCE_LIMIT"],
+      ["maxOutputResourceBytes", maxOutputResourceBytes, "INVALID_OUTPUT_RESOURCE_LIMIT"],
+      ["maxInputBytes", maxInputBytes, "INVALID_INPUT_BYTES_LIMIT"],
+      ["maxOutputBytes", maxOutputBytes, "INVALID_OUTPUT_BYTES_LIMIT"],
+      ["maxInputResources", maxInputResources, "INVALID_INPUT_COUNT_LIMIT"],
+      ["maxOutputResources", maxOutputResources, "INVALID_OUTPUT_COUNT_LIMIT"]
+    ]) {
+      if (limit !== Infinity && (!Number.isSafeInteger(limit) || limit < 0)) {
+        throw new TileConversionError(
+          code,
+          name + " must be a nonnegative safe integer or Infinity"
+        );
+      }
     }
     reportProgress("inspect");
-    const inspection = await inspectTileset(source, signal);
-    for await (const inputResource of source.read(inspection, signal)) {
+    const inspection = await measureConversionOperation(
+      timings,
+      "inspectMilliseconds",
+      () => inspectTileset(source, signal)
+    );
+    for await (const inputResource of measureConversionIterable(
+      source.read(inspection, signal),
+      timings,
+      "readMilliseconds"
+    )) {
       throwIfAborted(signal);
+      checkConversionTotal(inputResources, 1, maxInputResources, "INPUT_COUNT_LIMIT_EXCEEDED");
       const inputResourceBytes = measureInputBytes(inputResource);
       if (!Number.isSafeInteger(inputResourceBytes) || inputResourceBytes < 0) {
         throw new TileConversionError(
@@ -63,23 +95,53 @@ async function convertTileset(options) {
           `Input resource is ${inputResourceBytes} bytes, exceeding the configured limit of ${maxInputResourceBytes} bytes`
         );
       }
+      checkConversionTotal(
+        inputBytes,
+        inputResourceBytes,
+        maxInputBytes,
+        "INPUT_BYTES_LIMIT_EXCEEDED"
+      );
       inputResources++;
       inputBytes += inputResourceBytes;
       reportProgress("convert");
-      const convertedResources = await codec.convert(inputResource, inspection, signal);
-      for await (const outputResource of convertedResources) {
+      const convertedResources = await measureConversionOperation(
+        timings,
+        "convertMilliseconds",
+        () => codec.convert(inputResource, inspection, signal)
+      );
+      for await (const outputResource of measureConversionIterable(
+        convertedResources,
+        timings,
+        "convertMilliseconds"
+      )) {
         throwIfAborted(signal);
+        checkConversionTotal(outputResources, 1, maxOutputResources, "OUTPUT_COUNT_LIMIT_EXCEEDED");
         reportProgress("validate");
-        const resourceDiagnostics = await codec.validateOutput?.(outputResource, signal) || [];
+        const resourceDiagnostics = await measureConversionOperation(
+          timings,
+          "validateMilliseconds",
+          () => codec.validateOutput?.(outputResource, signal)
+        ) || [];
         diagnostics.push(...resourceDiagnostics);
         const outputResourceBytes = measureOutputBytes(outputResource);
-        largestOutputResourceBytes = Math.max(largestOutputResourceBytes, outputResourceBytes);
+        if (!Number.isSafeInteger(outputResourceBytes) || outputResourceBytes < 0) {
+          throw new TileConversionError(
+            "INVALID_OUTPUT_RESOURCE_SIZE",
+            "measureOutputBytes must return a nonnegative safe integer"
+          );
+        }
         if (outputResourceBytes > maxOutputResourceBytes) {
           throw new TileConversionError(
             "OUTPUT_RESOURCE_TOO_LARGE",
             `Output resource is ${outputResourceBytes} bytes, exceeding the configured limit of ${maxOutputResourceBytes} bytes`
           );
         }
+        checkConversionTotal(
+          outputBytes,
+          outputResourceBytes,
+          maxOutputBytes,
+          "OUTPUT_BYTES_LIMIT_EXCEEDED"
+        );
         if (resourceDiagnostics.some((diagnostic) => diagnostic.severity === "error")) {
           throw new TileConversionError(
             "OUTPUT_VALIDATION_FAILED",
@@ -88,8 +150,13 @@ async function convertTileset(options) {
           );
         }
         throwIfAborted(signal);
-        await sink.write(outputResource, signal);
+        await measureConversionOperation(
+          timings,
+          "writeMilliseconds",
+          () => sink.write(outputResource, signal)
+        );
         throwIfAborted(signal);
+        largestOutputResourceBytes = Math.max(largestOutputResourceBytes, outputResourceBytes);
         outputResources++;
         outputBytes += outputResourceBytes;
         reportProgress("convert");
@@ -106,8 +173,9 @@ async function convertTileset(options) {
     };
     throwIfAborted(signal);
     reportProgress("finalize");
-    await sink.finalize(report);
-    return report;
+    await measureConversionOperation(timings, "finalizeMilliseconds", () => sink.finalize(report));
+    if (timings) timings.totalMilliseconds = Math.max(0, performance.now() - started);
+    return timings ? { ...report, timings } : report;
   } catch (error) {
     try {
       await sink.abort(error);
@@ -134,6 +202,44 @@ function throwIfAborted(signal) {
     throw signal.reason ?? new DOMException("The operation was aborted", "AbortError");
   }
 }
+function checkConversionTotal(current, increment, limit, code) {
+  if (increment > limit - current) {
+    throw new TileConversionError(
+      code,
+      `Conversion exceeds cumulative limit ${limit}: ${current} processed, next resource adds ${increment}`
+    );
+  }
+  if (increment > Number.MAX_SAFE_INTEGER - current) {
+    throw new TileConversionError(
+      "RESOURCE_TOTAL_OVERFLOW",
+      "Conversion totals must remain safe integers"
+    );
+  }
+}
+function measureConversionOperation(timings, stage, operation) {
+  if (!timings) return operation();
+  const started = performance.now();
+  return (async () => {
+    try {
+      return await operation();
+    } finally {
+      timings[stage] += Math.max(0, performance.now() - started);
+    }
+  })();
+}
+function measureConversionIterable(iterable, timings, stage) {
+  if (!timings) return iterable;
+  return {
+    [Symbol.asyncIterator]() {
+      const iterator = iterable[Symbol.asyncIterator]();
+      return {
+        next: async () => measureConversionOperation(timings, stage, () => iterator.next()),
+        ...iterator.return ? { return: iterator.return.bind(iterator) } : {},
+        ...iterator.throw ? { throw: iterator.throw.bind(iterator) } : {}
+      };
+    }
+  };
+}
 
 // src/v5/browser-source.ts
 function createBrowserTileConversionSource(options) {
@@ -271,7 +377,7 @@ import {
   I3SSpatialTransformer,
   markTilesetSpatialReferenceTransformed,
   Tiles3DSpatialTransformer
-} from "@loaders.gl/tiles";
+} from "@loaders.gl/tiles-3d";
 import { Matrix4 } from "@math.gl/core";
 function createTiles3DConversionSpatialContext(discovered, options = {}) {
   const spatialReference = createConversionSpatialReference(discovered, options);
@@ -291,8 +397,8 @@ function createTiles3DConversionSpatialContext(discovered, options = {}) {
   const outputSpatialReference = transformer ? markTilesetSpatialReferenceTransformed(spatialReference) : spatialReference;
   return {
     spatialReference: outputSpatialReference,
-    transformPositions: (positions) => transformer ? transformer.transformPositions(positions) : Float64Array.from(positions),
-    transformNormals: (normals, positions) => transformer ? transformer.transformNormals(normals, positions) : Float32Array.from(normals),
+    transformPositions: (positions) => transformer ? transformer.transformPositions(positions) : copyNativePositions(positions),
+    transformNormals: (normals, positions) => transformer ? transformer.transformNormals(normals, positions) : copyNativeNormals(normals, positions),
     transformBoundingVolume: (volume, sourceTransform) => transformer ? transformer.transformBoundingVolume(volume, sourceTransform) : cloneBoundingVolume(volume)
   };
 }
@@ -314,16 +420,9 @@ function createI3SConversionSpatialContext(discovered, options = {}) {
   const outputSpatialReference = transformer ? transformer.spatialReference : spatialReference;
   let nativeNormalTransformer;
   const transformNativeNormals = (normals, positions, normalReferenceFrame) => {
+    validateNormalReferenceFrame(normalReferenceFrame);
+    const targetNormals = copyNativeNormals(normals, positions);
     if (!spatialReference.sourceCrs || ["local", "cartesian"].includes(spatialReference.coordinateFrame)) {
-      const targetNormals = Float32Array.from(normals);
-      for (let index = 0; index < normals.length; index += 3) {
-        const length = Math.hypot(normals[index], normals[index + 1], normals[index + 2]);
-        if (length) {
-          for (let axis = 0; axis < 3; axis++) {
-            targetNormals[index + axis] = normals[index + axis] / length;
-          }
-        }
-      }
       return targetNormals;
     }
     nativeNormalTransformer ||= createSpatialTransformer(
@@ -337,7 +436,7 @@ function createI3SConversionSpatialContext(discovered, options = {}) {
         options
       )
     );
-    return nativeNormalTransformer.transformNormals(normals, positions, normalReferenceFrame);
+    return nativeNormalTransformer.transformNormals(targetNormals, positions, normalReferenceFrame);
   };
   return {
     spatialReference: outputSpatialReference,
@@ -358,7 +457,7 @@ function createI3SConversionSpatialContext(discovered, options = {}) {
       };
     },
     transformPositionsAsync: (positions, sourceOrigin) => transformer ? transformer.transformPositionsAsync(positions, sourceOrigin) : Promise.resolve(createNativeI3SPositions(positions, sourceOrigin, spatialReference)),
-    transformNormals: (normals, positions, normalReferenceFrame) => transformer ? transformer.transformNormals(normals, positions, normalReferenceFrame) : Float32Array.from(normals),
+    transformNormals: (normals, positions, normalReferenceFrame) => transformer ? transformer.transformNormals(normals, positions, normalReferenceFrame) : transformNativeNormals(normals, positions, normalReferenceFrame),
     transformBoundingVolume: (bounds) => transformer ? transformer.transformBoundingVolume(bounds) : cloneI3SBounds(bounds),
     transformBoundingVolumeAsync: (bounds) => transformer ? transformer.transformBoundingVolumeAsync(bounds) : Promise.resolve(cloneI3SBounds(bounds))
   };
@@ -442,21 +541,30 @@ function cloneI3SBounds(bounds) {
   };
 }
 function createNativeI3SPositions(sourcePositions, sourceOrigin, spatialReference) {
-  if (sourcePositions.length % 3 !== 0 || sourceOrigin.length < 3) {
-    throw new Error("I3S positions and origin must contain complete xyz coordinates");
+  const sourcePositions64 = copyNativePositions(sourcePositions);
+  if (sourceOrigin.length !== 3 || Array.from(sourceOrigin).some((value) => !Number.isFinite(value))) {
+    throw new TileConversionError(
+      "SPATIAL_INPUT_INVALID",
+      "I3S origins require three finite coordinates"
+    );
   }
   const origin = [
     Number(sourceOrigin[0]),
     Number(sourceOrigin[1]),
     Number(sourceOrigin[2])
   ];
-  const sourcePositions64 = Float64Array.from(sourcePositions);
   const positions = new Float32Array(sourcePositions.length);
   for (let index = 0; index < sourcePositions.length; index += 3) {
     positions[index] = Number(sourcePositions[index]) - origin[0];
     positions[index + 1] = Number(sourcePositions[index + 1]) - origin[1];
     positions[index + 2] = Number(sourcePositions[index + 2]) - origin[2];
   }
+  if (positions.some((value) => !Number.isFinite(value))) {
+    throw new TileConversionError(
+      "SPATIAL_INPUT_INVALID",
+      "Native I3S offsets exceed float32 range"
+    );
+  }
   const isGeographic = spatialReference.coordinateFrame === "geographic";
   const modelMatrix = isGeographic ? new Matrix4() : new Matrix4().translate(origin);
   return {
@@ -468,9 +576,64 @@ function createNativeI3SPositions(sourcePositions, sourceOrigin, spatialReferenc
     modelMatrix
   };
 }
+function copyNativePositions(positions) {
+  validateNativePositions(positions);
+  return Float64Array.from(positions);
+}
+function validateNativePositions(positions) {
+  if (positions.length % 3) {
+    throw new TileConversionError(
+      "SPATIAL_INPUT_INVALID",
+      "Positions require complete finite xyz coordinates"
+    );
+  }
+  for (let index = 0; index < positions.length; index++) {
+    if (!Number.isFinite(positions[index])) {
+      throw new TileConversionError(
+        "SPATIAL_INPUT_INVALID",
+        "Positions require complete finite xyz coordinates"
+      );
+    }
+  }
+}
+function copyNativeNormals(normals, positions) {
+  validateNativePositions(positions);
+  if (normals.length !== positions.length) {
+    throw new TileConversionError(
+      "SPATIAL_INPUT_INVALID",
+      "Normals require finite xyz values matching positions"
+    );
+  }
+  const output = new Float32Array(normals.length);
+  for (let index = 0; index < normals.length; index += 3) {
+    const scale = Math.max(
+      Math.abs(normals[index]),
+      Math.abs(normals[index + 1]),
+      Math.abs(normals[index + 2])
+    );
+    if (!Number.isFinite(scale)) {
+      throw new TileConversionError(
+        "SPATIAL_INPUT_INVALID",
+        "Normals require finite xyz values matching positions"
+      );
+    }
+    const length = scale ? Math.hypot(normals[index] / scale, normals[index + 1] / scale, normals[index + 2] / scale) : 0;
+    for (let axis = 0; axis < 3; axis++)
+      output[index + axis] = length ? normals[index + axis] / scale / length : 0;
+  }
+  return output;
+}
+function validateNormalReferenceFrame(frame) {
+  if (frame !== void 0 && !["earth-centered", "vertex-reference-frame"].includes(frame)) {
+    throw new TileConversionError(
+      "SPATIAL_INPUT_INVALID",
+      "Unsupported I3S normal reference frame"
+    );
+  }
+}
 
 // src/v5/tileset-source.ts
-import { traverseTilesetContents } from "@loaders.gl/tiles";
+import { traverseTilesetContents } from "@loaders.gl/tiles-3d";
 function createTilesetConversionSource(tileset, options = {}) {
   return {
     async inspect(signal) {
@@ -492,10 +655,17 @@ function createTilesetConversionSource(tileset, options = {}) {
 // src/v5/resource-manifest.ts
 var TILE_RESOURCE_MANIFEST_VERSION = 1;
 async function createManifestBackedTileConversionSink(options) {
+  const maxResources = options.maxResources ?? Infinity;
+  if (maxResources !== Infinity && (!Number.isSafeInteger(maxResources) || maxResources < 0)) {
+    throw new TileConversionError(
+      "INVALID_MANIFEST_RESOURCE_LIMIT",
+      "maxResources must be a nonnegative safe integer or Infinity"
+    );
+  }
   const priorManifest = await options.manifestStore.load();
   const resources = /* @__PURE__ */ new Map();
   if (priorManifest) {
-    validateManifest(priorManifest);
+    validateManifest(priorManifest, maxResources);
     for (const entry of priorManifest.resources) {
       resources.set(entry.resourceId, entry);
     }
@@ -521,6 +691,7 @@ async function createManifestBackedTileConversionSink(options) {
     if (writeFailed) {
       throw writeFailure;
     }
+    signal?.throwIfAborted();
     const entry = createManifestEntry(options, resource);
     const priorEntry = resources.get(entry.resourceId);
     if (priorEntry) {
@@ -530,7 +701,14 @@ async function createManifestBackedTileConversionSink(options) {
           `Resource "${entry.resourceId}" changed since the saved manifest`
         );
       }
-      return;
+      const verified = options.verifyResource ? await options.verifyResource({ ...priorEntry }, signal) : true;
+      signal?.throwIfAborted();
+      if (verified === true) return;
+    } else if (resources.size >= maxResources) {
+      throw new TileConversionError(
+        "MANIFEST_RESOURCE_LIMIT_EXCEEDED",
+        "Resource checkpoint exceeds maxResources"
+      );
     }
     await options.sink.write(resource, signal);
     resources.set(entry.resourceId, entry);
@@ -579,11 +757,17 @@ function createManifestEntry(options, resource) {
   }
   return { resourceId, byteLength, fingerprint };
 }
-function validateManifest(manifest) {
+function validateManifest(manifest, maxResources) {
   if (typeof manifest !== "object" || manifest === null || manifest.version !== TILE_RESOURCE_MANIFEST_VERSION || typeof manifest.complete !== "boolean" || !Array.isArray(manifest.resources)) {
     throw new TileConversionError(
       "UNSUPPORTED_RESOURCE_MANIFEST",
-      `Unsupported or malformed resource manifest version: ${String(manifest.version)}`
+      `Unsupported or malformed resource manifest version: ${String(manifest?.version)}`
+    );
+  }
+  if (manifest.resources.length > maxResources) {
+    throw new TileConversionError(
+      "MANIFEST_RESOURCE_LIMIT_EXCEEDED",
+      "Loaded manifest exceeds maxResources"
     );
   }
   const resourceIds = /* @__PURE__ */ new Set();
@@ -675,50 +859,67 @@ function measureBlobPart(part) {
 
 // src/v5/browser-tileset-source.ts
 function createBrowserTilesetConversionSource(options) {
-  if (!Number.isSafeInteger(options.maxInputBytes) || options.maxInputBytes < 1 || !Number.isSafeInteger(options.maxInputResources) || options.maxInputResources < 1) {
+  const maxTilesetDocuments = options.maxTilesetDocuments ?? 1;
+  if (options.inspectNestedTilesets !== void 0 && typeof options.inspectNestedTilesets !== "boolean" || !Number.isSafeInteger(maxTilesetDocuments) || maxTilesetDocuments < 1 || !Number.isSafeInteger(options.maxInputBytes) || options.maxInputBytes < 1 || !Number.isSafeInteger(options.maxInputResources) || options.maxInputResources < 1) {
     throw new TileConversionError(
       "INVALID_BROWSER_SOURCE_OPTIONS",
-      "Browser tileset sources require positive byte and resource limits"
+      "Browser tileset sources require positive byte, declaration and document limits"
     );
   }
   const fetcher = options.fetcher ?? fetch;
   return {
     async inspect(signal) {
       throwIfAborted4(signal);
-      const rootUrl = new URL(options.input).href;
-      const response = await fetcher(rootUrl, { signal });
+      const requestedUrl = new URL(options.input).href;
+      const response = await fetcher(requestedUrl, { signal });
+      const rootUrl = response.url || requestedUrl;
       if (!response.ok) {
+        await response.body?.cancel();
         throw new TileConversionError(
           "BROWSER_SOURCE_FETCH_FAILED",
           `Could not fetch browser tileset (${response.status} ${response.statusText})`
         );
       }
       const data = await readResponseBytes2(response, options.maxInputBytes, signal);
-      let tileset;
-      try {
-        tileset = JSON.parse(new TextDecoder().decode(data));
-      } catch {
-        throw new TileConversionError("INVALID_BROWSER_TILESET", "Tileset input is not valid JSON");
-      }
-      if (!isRecord(tileset) || !["1.0", "1.1"].includes(tileset.asset?.version || "") || !isRecord(tileset.root)) {
-        throw new TileConversionError(
-          "UNSUPPORTED_BROWSER_TILESET",
-          "Browser tileset traversal supports explicit 3D Tiles 1.0 and 1.1 documents"
-        );
-      }
+      const tileset = parseTilesetDocument(data);
       const resources = collectResources(tileset.root, options.maxInputResources);
-      return { rootUrl, tileset, resources, tilesetBytes: data.byteLength };
+      const inspection = { rootUrl, tileset, resources, tilesetBytes: data.byteLength };
+      return options.inspectNestedTilesets ? expandInspection(inspection, options, maxTilesetDocuments, fetcher, signal) : inspection;
     },
     async *read(inspection, signal) {
       let inputBytes = inspection.tilesetBytes;
-      for (const descriptor of inspection.resources) {
+      let declarations = inspection.resources.length;
+      let documents = 1;
+      const stack = [
+        {
+          resources: inspection.resources,
+          index: 0,
+          tileset: inspection.tileset,
+          url: inspection.rootUrl,
+          ancestors: /* @__PURE__ */ new Set([getDocumentKey(inspection.rootUrl), getDocumentKey(options.input)])
+        }
+      ];
+      while (stack.length) {
         throwIfAborted4(signal);
-        const resourceUrl = resolveResourceUrl(descriptor.uri, inspection.rootUrl);
+        const frame = stack[stack.length - 1];
+        if (frame.index === frame.resources.length) {
+          stack.pop();
+          continue;
+        }
+        const descriptor = frame.resources[frame.index++];
+        const resourceUrl = resolveResourceUrl(descriptor.uri, descriptor.tilesetUrl ?? frame.url);
+        if (frame.ancestors.has(getDocumentKey(resourceUrl))) {
+          throw new TileConversionError(
+            "BROWSER_TILESET_CYCLE",
+            "External tileset references an active ancestor document"
+          );
+        }
         const response = await fetcher(resourceUrl, { signal });
         if (!response.ok) {
+          await response.body?.cancel();
           throw new TileConversionError(
             "BROWSER_SOURCE_FETCH_FAILED",
-            `Could not fetch browser tile content (${response.status} ${response.statusText})`,
+            "Could not fetch browser tile content (" + response.status + " " + response.statusText + ")",
             [
               {
                 code: "BROWSER_SOURCE_FETCH_FAILED",
@@ -729,28 +930,280 @@ function createBrowserTilesetConversionSource(options) {
             ]
           );
         }
-        const remainingBytes = options.maxInputBytes - inputBytes;
-        const data = await readResponseBytes2(response, remainingBytes, signal);
+        const documentUrl = response.url || resourceUrl;
+        if (frame.ancestors.has(getDocumentKey(documentUrl))) {
+          await response.body?.cancel();
+          throw new TileConversionError(
+            "BROWSER_TILESET_CYCLE",
+            "Redirected content references an active ancestor document"
+          );
+        }
+        const data = await readResponseBytes2(response, options.maxInputBytes - inputBytes, signal);
         inputBytes += data.byteLength;
         const contentType = response.headers.get("content-type") ?? void 0;
         if (isJsonContent(data, contentType)) {
-          throw new TileConversionError(
-            "UNSUPPORTED_BROWSER_TILESET_CONTENT",
-            `Nested tilesets and JSON tile content are not supported: ${descriptor.uri}`
-          );
+          if (inspection.documents)
+            throw new TileConversionError(
+              "UNSUPPORTED_BROWSER_TILESET_CONTENT",
+              "Expanded inspection selections must be binary content; declare external metadata with a .json URI"
+            );
+          if (maxTilesetDocuments === 1) {
+            throw new TileConversionError(
+              "UNSUPPORTED_BROWSER_TILESET_CONTENT",
+              "Nested tilesets and JSON tile content require an explicit document budget"
+            );
+          }
+          if (documents >= maxTilesetDocuments) {
+            throw new TileConversionError(
+              "INPUT_TILESET_COUNT_EXCEEDED",
+              "Browser tileset exceeds its document limit"
+            );
+          }
+          let tile = frame.tileset.root;
+          for (const childIndex of descriptor.tilePath) tile = getTileChild(tile, childIndex);
+          if (tile.children?.length) {
+            throw new TileConversionError(
+              "INVALID_BROWSER_TILESET",
+              "External tileset references cannot also have child tiles"
+            );
+          }
+          const tileset = parseTilesetDocument(data);
+          const resources = collectResources(
+            tileset.root,
+            options.maxInputResources - declarations,
+            descriptor.transform
+          ).map((resource) => ({
+            ...resource,
+            resourceId: descriptor.resourceId + "/" + resource.resourceId,
+            tilesetUrl: documentUrl
+          }));
+          declarations += resources.length;
+          documents++;
+          stack.push({
+            resources,
+            index: 0,
+            tileset,
+            url: documentUrl,
+            ancestors: /* @__PURE__ */ new Set([
+              ...frame.ancestors,
+              getDocumentKey(resourceUrl),
+              getDocumentKey(documentUrl)
+            ])
+          });
+          continue;
         }
-        yield { ...descriptor, data, ...contentType ? { contentType } : {} };
+        yield { ...descriptor, data, contentUrl: documentUrl, ...contentType ? { contentType } : {} };
       }
     }
   };
 }
-function collectResources(root, maxInputResources) {
+function selectBrowserTilesetContent(inspection, descriptor) {
+  const placement = inspection.documents?.[descriptor.documentIndex ?? 0];
+  if (inspection.documents && (!Number.isSafeInteger(descriptor.documentIndex) || !placement))
+    throw new TileConversionError(
+      "INVALID_BROWSER_SELECTION",
+      "Content descriptor has no inspected document placement"
+    );
+  const document = structuredClone(placement?.tileset ?? inspection.tileset);
+  const originalRoot = document.root;
+  let transform = [...placement?.parentTransform ?? identityMatrix()];
+  let maximum = placement?.parentGeometricError ?? 0;
+  let tile = originalRoot;
+  for (let depth = 0; ; depth++) {
+    transform = multiplyMatrices(transform, normalizeMatrix(tile.transform));
+    if (typeof tile.geometricError !== "number" || !Number.isFinite(tile.geometricError) || tile.geometricError < 0)
+      throw new TileConversionError(
+        "MESH_GEOMETRIC_ERROR_INVALID",
+        "Every selected ancestor must declare a finite nonnegative geometricError"
+      );
+    maximum = Math.max(maximum, tile.geometricError * getTransformScale(transform));
+    if (depth === descriptor.tilePath.length) break;
+    const child = getTileChild(tile, descriptor.tilePath[depth]);
+    delete tile.content;
+    delete tile.contents;
+    tile.children = [child];
+    tile = child;
+  }
+  if (placement && placement.parentGeometricError === void 0 && descriptor.documentIndex !== 0)
+    throw new TileConversionError(
+      "MESH_GEOMETRIC_ERROR_INVALID",
+      "External ancestors must declare geometricError"
+    );
+  const isLeaf = !tile.children?.length;
+  const contentIndex = Number(descriptor.resourceId.match(/content-(\d+)$/)?.[1]);
+  const content = tile.contents?.[contentIndex] ?? tile.content;
+  if (!content || (content.uri ?? content.url) !== descriptor.uri)
+    throw new TileConversionError(
+      "INVALID_BROWSER_SELECTION",
+      "Content descriptor does not match its inspected document"
+    );
+  tile.content = content;
+  delete tile.contents;
+  delete tile.children;
+  if (placement)
+    originalRoot.transform = multiplyMatrices(
+      [...placement.parentTransform],
+      normalizeMatrix(originalRoot.transform)
+    );
+  if (!Number.isFinite(maximum))
+    throw new TileConversionError(
+      "MESH_GEOMETRIC_ERROR_INVALID",
+      "Scaled geometricError must remain finite"
+    );
+  return {
+    tileset: document,
+    contentUrl: resolveResourceUrl(descriptor.uri, placement?.url ?? inspection.rootUrl),
+    geometricError: maximum,
+    isLeaf
+  };
+}
+function getTileChild(tile, childIndex) {
+  if (typeof childIndex !== "number" || !Number.isSafeInteger(childIndex) || childIndex < 0 || !Array.isArray(tile.children) || childIndex >= tile.children.length)
+    throw new TileConversionError(
+      "INVALID_BROWSER_SELECTION",
+      "Tile paths require in-bounds nonnegative integer child indexes"
+    );
+  const child = tile.children.at(childIndex);
+  if (!isRecord(child))
+    throw new TileConversionError(
+      "INVALID_BROWSER_SELECTION",
+      "Selected child tile must be an object"
+    );
+  return child;
+}
+async function expandInspection(inspection, options, maxTilesetDocuments, fetcher, signal) {
+  const documents = [
+    {
+      url: inspection.rootUrl,
+      tileset: inspection.tileset,
+      parentTransform: identityMatrix(),
+      parentGeometricError: 0
+    }
+  ];
   const resources = [];
+  let bytes = inspection.tilesetBytes;
+  let declarations = inspection.resources.length;
   const stack = [
-    { tile: root, path: [], transform: identityMatrix() }
+    {
+      resources: inspection.resources,
+      index: 0,
+      documentIndex: 0,
+      ancestors: /* @__PURE__ */ new Set([getDocumentKey(inspection.rootUrl), getDocumentKey(options.input)])
+    }
+  ];
+  while (stack.length) {
+    throwIfAborted4(signal);
+    const frame = stack[stack.length - 1];
+    if (frame.index === frame.resources.length) {
+      stack.pop();
+      continue;
+    }
+    const descriptor = frame.resources[frame.index++];
+    const placement = documents[frame.documentIndex];
+    const resourceUrl = resolveResourceUrl(descriptor.uri, placement.url);
+    if (!new URL(resourceUrl).pathname.toLowerCase().endsWith(".json")) {
+      resources.push({ ...descriptor, documentIndex: frame.documentIndex });
+      continue;
+    }
+    if (frame.ancestors.has(getDocumentKey(resourceUrl)))
+      throw new TileConversionError(
+        "BROWSER_TILESET_CYCLE",
+        "External tileset references an active ancestor document"
+      );
+    if (documents.length >= maxTilesetDocuments)
+      throw new TileConversionError(
+        "INPUT_TILESET_COUNT_EXCEEDED",
+        "Browser tileset exceeds its document limit"
+      );
+    let tile = placement.tileset.root;
+    for (const childIndex of descriptor.tilePath) tile = tile.children[childIndex];
+    if (tile.children?.length || tile.contents?.length)
+      throw new TileConversionError(
+        "INVALID_BROWSER_TILESET",
+        "Inspected external tilesets require one content and no child tiles"
+      );
+    const response = await fetcher(resourceUrl, { signal });
+    const url = response.url || resourceUrl;
+    if (!response.ok || frame.ancestors.has(getDocumentKey(url))) {
+      await response.body?.cancel();
+      throw new TileConversionError(
+        response.ok ? "BROWSER_TILESET_CYCLE" : "BROWSER_SOURCE_FETCH_FAILED",
+        "Could not inspect external tileset"
+      );
+    }
+    const data = await readResponseBytes2(response, options.maxInputBytes - bytes, signal);
+    bytes += data.byteLength;
+    const tileset = parseTilesetDocument(data);
+    const prefix = descriptor.resourceId + "/";
+    const nestedResources = collectResources(
+      tileset.root,
+      options.maxInputResources - declarations,
+      descriptor.transform
+    ).map((resource) => ({ ...resource, resourceId: prefix + resource.resourceId, tilesetUrl: url }));
+    declarations += nestedResources.length;
+    let parentGeometricError;
+    try {
+      parentGeometricError = selectBrowserTilesetContent(
+        { ...inspection, documents },
+        { ...descriptor, documentIndex: frame.documentIndex }
+      ).geometricError;
+    } catch (error) {
+      if (!(error instanceof TileConversionError) || error.code !== "MESH_GEOMETRIC_ERROR_INVALID")
+        throw error;
+    }
+    const documentIndex = documents.length;
+    documents.push({
+      url,
+      tileset,
+      parentResourceId: descriptor.resourceId,
+      parentTransform: descriptor.transform,
+      parentGeometricError
+    });
+    stack.push({
+      resources: nestedResources,
+      index: 0,
+      documentIndex,
+      ancestors: /* @__PURE__ */ new Set([...frame.ancestors, getDocumentKey(resourceUrl), getDocumentKey(url)])
+    });
+  }
+  return { ...inspection, resources, documents, tilesetBytes: bytes };
+}
+function getTransformScale(transform) {
+  const columns = [0, 1, 2].map(
+    (column) => [0, 1, 2].reduce((total, row) => total + Math.abs(transform[column * 4 + row]), 0)
+  );
+  const rows = [0, 1, 2].map(
+    (row) => [0, 1, 2].reduce((total, column) => total + Math.abs(transform[column * 4 + row]), 0)
+  );
+  return Math.sqrt(Math.max(...columns)) * Math.sqrt(Math.max(...rows));
+}
+function parseTilesetDocument(data) {
+  let tileset;
+  try {
+    tileset = JSON.parse(new TextDecoder().decode(data));
+  } catch {
+    throw new TileConversionError("INVALID_BROWSER_TILESET", "Tileset input is not valid JSON");
+  }
+  if (!isRecord(tileset) || !["1.0", "1.1"].includes(tileset.asset?.version || "") || !isRecord(tileset.root)) {
+    throw new TileConversionError(
+      "UNSUPPORTED_BROWSER_TILESET",
+      "Browser tileset traversal supports explicit 3D Tiles 1.0 and 1.1 documents"
+    );
+  }
+  return tileset;
+}
+function getDocumentKey(url) {
+  const documentUrl = new URL(url);
+  documentUrl.hash = "";
+  return documentUrl.href;
+}
+function collectResources(root, maxInputResources, parentTransform = identityMatrix()) {
+  const resources = [];
+  const stack = [
+    { tile: root, path: [], transform: [...parentTransform] }
   ];
   while (stack.length > 0) {
-    const { tile, path, transform: parentTransform } = stack.pop();
+    const { tile, path, transform: parentTransform2 } = stack.pop();
     if (!isRecord(tile)) {
       throw new TileConversionError("INVALID_BROWSER_TILESET", "Tile entries must be objects");
     }
@@ -766,7 +1219,19 @@ function collectResources(root, maxInputResources) {
     if (tile.children !== void 0 && !Array.isArray(tile.children)) {
       throw new TileConversionError("INVALID_BROWSER_TILESET", "Tile children must be an array");
     }
-    const transform = multiplyMatrices(parentTransform, normalizeMatrix(tile.transform));
+    if (tile.content !== void 0 && tile.contents !== void 0) {
+      throw new TileConversionError(
+        "INVALID_BROWSER_TILESET",
+        "Tile content and contents are mutually exclusive"
+      );
+    }
+    const transform = multiplyMatrices(parentTransform2, normalizeMatrix(tile.transform));
+    if (transform.some((value) => !Number.isFinite(value))) {
+      throw new TileConversionError(
+        "INVALID_BROWSER_TILESET",
+        "Composed tile transforms must remain finite"
+      );
+    }
     const contents = tile.contents ?? (tile.content ? [tile.content] : []);
     for (let contentIndex = 0; contentIndex < contents.length; contentIndex++) {
       const content = contents[contentIndex];
@@ -815,15 +1280,15 @@ async function readResponseBytes2(response, maximumBytes, signal) {
       "Browser inputs must provide a readable response stream"
     );
   }
-  const data = new Uint8Array(maximumBytes);
   let byteLength = 0;
   try {
+    const data = new Uint8Array(maximumBytes);
     while (true) {
       throwIfAborted4(signal);
       const { done, value } = await reader.read();
+      throwIfAborted4(signal);
       if (done) break;
       if (value.byteLength > maximumBytes - byteLength) {
-        await reader.cancel();
         throw new TileConversionError(
           "INPUT_RESOURCE_TOO_LARGE",
           `Browser tileset input exceeds the configured ${maximumBytes} byte remaining limit`
@@ -832,10 +1297,14 @@ async function readResponseBytes2(response, maximumBytes, signal) {
       data.set(value, byteLength);
       byteLength += value.byteLength;
     }
+    return data.slice(0, byteLength);
+  } catch (error) {
+    await reader.cancel().catch(() => {
+    });
+    throw error;
   } finally {
     reader.releaseLock();
   }
-  return data.subarray(0, byteLength);
 }
 function isJsonContent(data, contentType) {
   if (contentType?.includes("json")) return true;
@@ -894,6 +1363,7 @@ export {
   createTiles3DConversionSpatialContext,
   createTilesetConversionSource,
   inspectTileset,
+  selectBrowserTilesetContent,
   traversePointCloudSource,
   validateTileset
 };