@loaders.gl/tile-converter 5.0.0-alpha.7 → 5.0.0-alpha.8

package/src/v5/browser-tileset-source.ts

@@ -0,0 +1,328 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TileConversionError} from './conversion-api.js';
+import type {TileConversionSource} from './conversion-api.js';
+
+type TilesetContent = {uri?: string; url?: string};
+type TilesetTile = {
+  content?: TilesetContent;
+  contents?: TilesetContent[];
+  children?: TilesetTile[];
+  transform?: number[];
+  implicitTiling?: unknown;
+  extensions?: Record<string, unknown>;
+};
+type TilesetDocument = {asset?: {version?: string}; root?: TilesetTile};
+
+/** Input options for bounded traversal of one explicit 3D Tiles tileset. */
+export interface BrowserTilesetConversionSourceOptions {
+  /** URL of the root tileset JSON document. */
+  readonly input: string;
+  /** Maximum bytes retained across the tileset JSON and all content resources. */
+  readonly maxInputBytes: number;
+  /** Maximum number of content resources to visit. */
+  readonly maxInputResources: number;
+  /** Fetch implementation, defaulting to the browser global. */
+  readonly fetcher?: typeof fetch;
+}
+
+/** Inspection result for an explicit 3D Tiles source. */
+export interface BrowserTilesetConversionInspection {
+  /** Absolute URL of the root tileset document. */
+  readonly rootUrl: string;
+  /** Parsed root document used for deterministic content traversal. */
+  readonly tileset: TilesetDocument;
+  /** Ordered content descriptors. */
+  readonly resources: readonly BrowserTilesetResourceDescriptor[];
+  /** Root document bytes charged against the input limit. */
+  readonly tilesetBytes: number;
+}
+
+/** Placement metadata for one ordered content resource. */
+export interface BrowserTilesetResourceDescriptor {
+  /** Unique, stable path for this content placement. */
+  readonly resourceId: string;
+  /** Original URI declared by the tileset. */
+  readonly uri: string;
+  /** Tile child indexes from the tileset root. */
+  readonly tilePath: readonly number[];
+  /** Combined root-to-tile transform in column-major order. */
+  readonly transform: readonly number[];
+}
+
+/** One raw content resource from a browser-readable explicit tileset. */
+export interface BrowserTilesetConversionInputResource extends BrowserTilesetResourceDescriptor {
+  /** Complete content bytes for an injected profile-specific codec. */
+  readonly data: Uint8Array;
+  /** Optional content type reported by the response. */
+  readonly contentType?: string;
+}
+
+/**
+ * Creates a bounded browser source for explicit 3D Tiles 1.0 and 1.1 tilesets.
+ *
+ * Traversal visits each declared content placement once in depth-first order. Implicit tiling and
+ * nested external tilesets are rejected; content decoding and conversion remain codec work.
+ *
+ * @param options - Tileset URL and aggregate byte and resource limits.
+ * @returns A source yielding ordered raw tile resources with placement transforms.
+ */
+export function createBrowserTilesetConversionSource(
+  options: BrowserTilesetConversionSourceOptions
+): TileConversionSource<BrowserTilesetConversionInspection, BrowserTilesetConversionInputResource> {
+  if (
+    !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'
+    );
+  }
+
+  const fetcher = options.fetcher ?? fetch;
+  return {
+    async inspect(signal) {
+      throwIfAborted(signal);
+      const rootUrl = new URL(options.input).href;
+      const response = await fetcher(rootUrl, {signal});
+      if (!response.ok) {
+        throw new TileConversionError(
+          'BROWSER_SOURCE_FETCH_FAILED',
+          `Could not fetch browser tileset (${response.status} ${response.statusText})`
+        );
+      }
+      const data = await readResponseBytes(response, options.maxInputBytes, signal);
+      let tileset: TilesetDocument;
+      try {
+        tileset = JSON.parse(new TextDecoder().decode(data)) as TilesetDocument;
+      } 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 resources = collectResources(tileset.root, options.maxInputResources);
+      return {rootUrl, tileset, resources, tilesetBytes: data.byteLength};
+    },
+    async *read(inspection, signal) {
+      let inputBytes = inspection.tilesetBytes;
+      for (const descriptor of inspection.resources) {
+        throwIfAborted(signal);
+        const resourceUrl = resolveResourceUrl(descriptor.uri, inspection.rootUrl);
+        const response = await fetcher(resourceUrl, {signal});
+        if (!response.ok) {
+          throw new TileConversionError(
+            'BROWSER_SOURCE_FETCH_FAILED',
+            `Could not fetch browser tile content (${response.status} ${response.statusText})`,
+            [
+              {
+                code: 'BROWSER_SOURCE_FETCH_FAILED',
+                message: resourceUrl,
+                severity: 'error',
+                resourceId: descriptor.resourceId
+              }
+            ]
+          );
+        }
+        const remainingBytes = options.maxInputBytes - inputBytes;
+        const data = await readResponseBytes(response, remainingBytes, signal);
+        inputBytes += data.byteLength;
+        const contentType = response.headers.get('content-type') ?? undefined;
+        if (isJsonContent(data, contentType)) {
+          throw new TileConversionError(
+            'UNSUPPORTED_BROWSER_TILESET_CONTENT',
+            `Nested tilesets and JSON tile content are not supported: ${descriptor.uri}`
+          );
+        }
+        yield {...descriptor, data, ...(contentType ? {contentType} : {})};
+      }
+    }
+  };
+}
+
+/** Collects explicit tile contents in declaration order and fails on unbounded formats. */
+function collectResources(
+  root: TilesetTile,
+  maxInputResources: number
+): BrowserTilesetResourceDescriptor[] {
+  const resources: BrowserTilesetResourceDescriptor[] = [];
+  const stack: Array<{tile: TilesetTile; path: number[]; transform: number[]}> = [
+    {tile: root, path: [], transform: identityMatrix()}
+  ];
+  while (stack.length > 0) {
+    const {tile, path, transform: parentTransform} = stack.pop()!;
+    if (!isRecord(tile)) {
+      throw new TileConversionError('INVALID_BROWSER_TILESET', 'Tile entries must be objects');
+    }
+    if (
+      tile.implicitTiling !== undefined ||
+      tile.extensions?.['3DTILES_implicit_tiling'] !== undefined
+    ) {
+      throw new TileConversionError(
+        'UNSUPPORTED_BROWSER_TILESET',
+        'Browser tileset traversal does not yet support implicit tiling'
+      );
+    }
+    if (tile.contents !== undefined && !Array.isArray(tile.contents)) {
+      throw new TileConversionError('INVALID_BROWSER_TILESET', 'Tile contents must be an array');
+    }
+    if (tile.children !== undefined && !Array.isArray(tile.children)) {
+      throw new TileConversionError('INVALID_BROWSER_TILESET', 'Tile children must be an array');
+    }
+    const transform = multiplyMatrices(parentTransform, normalizeMatrix(tile.transform));
+    const contents = tile.contents ?? (tile.content ? [tile.content] : []);
+    for (let contentIndex = 0; contentIndex < contents.length; contentIndex++) {
+      const content = contents[contentIndex];
+      if (!isRecord(content)) {
+        throw new TileConversionError(
+          'INVALID_BROWSER_TILESET',
+          'Tile content entries must be objects'
+        );
+      }
+      const uri = content.uri ?? content.url;
+      if (typeof uri !== 'string' || !uri) {
+        throw new TileConversionError(
+          'INVALID_BROWSER_TILESET',
+          `Tile content at ${path.join('/')} has no URI`
+        );
+      }
+      if (resources.length >= maxInputResources) {
+        throw new TileConversionError(
+          'INPUT_RESOURCE_COUNT_EXCEEDED',
+          `Browser tileset exceeds the configured ${maxInputResources} resource limit`
+        );
+      }
+      resources.push({
+        resourceId: `tile-${path.length ? path.join('-') : 'root'}-content-${contentIndex}`,
+        uri,
+        tilePath: path,
+        transform
+      });
+    }
+    const children = tile.children ?? [];
+    for (let childIndex = children.length - 1; childIndex >= 0; childIndex--) {
+      stack.push({
+        tile: children[childIndex],
+        path: [...path, childIndex],
+        transform
+      });
+    }
+  }
+  return resources;
+}
+
+/** Reads one response into a single buffer without exceeding its remaining byte budget. */
+async function readResponseBytes(
+  response: Response,
+  maximumBytes: number,
+  signal?: AbortSignal
+): Promise<Uint8Array> {
+  const reader = response.body?.getReader();
+  if (!reader) {
+    throw new TileConversionError(
+      'BROWSER_SOURCE_STREAM_UNAVAILABLE',
+      'Browser inputs must provide a readable response stream'
+    );
+  }
+  const data = new Uint8Array(maximumBytes);
+  let byteLength = 0;
+  try {
+    while (true) {
+      throwIfAborted(signal);
+      const {done, value} = await reader.read();
+      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`
+        );
+      }
+      data.set(value, byteLength);
+      byteLength += value.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return data.subarray(0, byteLength);
+}
+
+/** Detects JSON payloads that may declare an unsupported external tileset. */
+function isJsonContent(data: Uint8Array, contentType?: string): boolean {
+  if (contentType?.includes('json')) return true;
+  let byteOffset = data[0] === 0xef && data[1] === 0xbb && data[2] === 0xbf ? 3 : 0;
+  while ([0x09, 0x0a, 0x0d, 0x20].includes(data[byteOffset])) byteOffset++;
+  return data[byteOffset] === 0x7b;
+}
+
+/** Resolves a tile URI and carries root query parameters to same-origin relative resources. */
+function resolveResourceUrl(uri: string, rootUrl: string): string {
+  const root = new URL(rootUrl);
+  const resource = new URL(uri, root);
+  if (resource.origin === root.origin) {
+    for (const [name, value] of root.searchParams) {
+      if (!resource.searchParams.has(name)) resource.searchParams.append(name, value);
+    }
+  }
+  return resource.href;
+}
+
+/** Returns whether a JSON value is a non-array object. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/** Returns an identity matrix in column-major order. */
+function identityMatrix(): number[] {
+  return [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+}
+
+/** Validates and copies a tile's optional column-major transform. */
+function normalizeMatrix(matrix?: number[]): number[] {
+  if (matrix === undefined) return identityMatrix();
+  if (
+    !Array.isArray(matrix) ||
+    matrix.length !== 16 ||
+    matrix.some(value => !Number.isFinite(value))
+  ) {
+    throw new TileConversionError(
+      'INVALID_BROWSER_TILESET',
+      'Tile transform must contain 16 finite numbers'
+    );
+  }
+  return matrix;
+}
+
+/** Multiplies column-major 4x4 matrices. */
+function multiplyMatrices(left: number[], right: number[]): number[] {
+  const result = new Array<number>(16);
+  for (let column = 0; column < 4; column++) {
+    for (let row = 0; row < 4; row++) {
+      result[column * 4 + row] =
+        left[row] * right[column * 4] +
+        left[4 + row] * right[column * 4 + 1] +
+        left[8 + row] * right[column * 4 + 2] +
+        left[12 + row] * right[column * 4 + 3];
+    }
+  }
+  return result;
+}
+
+/** Throws the signal reason when a browser source operation has been canceled. */
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+  }
+}

package/src/v5/browser.ts

@@ -0,0 +1,54 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export {
+  convertTileset,
+  inspectTileset,
+  TileConversionError,
+  validateTileset
+} from './conversion-api.js';
+export {createTilesetConversionSource} from './tileset-source.js';
+export type {TilesetConversionSourceOptions} from './tileset-source.js';
+export type {
+  ConvertTilesetOptions,
+  TileConversionCodec,
+  TileConversionDiagnostic,
+  TileConversionProgress,
+  TileConversionReport,
+  TileConversionSink,
+  TileConversionSource,
+  TileValidationReport,
+  ValidateTilesetOptions
+} from './conversion-api.js';
+export {createBoundedMemoryTileConversionSink} from './browser-sink.js';
+export {createBrowserTileConversionSource} from './browser-source.js';
+export type {
+  BoundedMemoryTileConversionSink,
+  BoundedMemoryTileConversionSinkOptions,
+  BrowserTileConversionFile,
+  BrowserTileConversionResource
+} from './browser-sink.js';
+export type {
+  BrowserTileConversionInspection,
+  BrowserTileConversionInputResource,
+  BrowserTileConversionSourceOptions
+} from './browser-source.js';
+export {createBrowserTilesetConversionSource} from './browser-tileset-source.js';
+export {encodePointCloudTile} from './point-cloud.js';
+export type {EncodePointCloudTileOptions} from './point-cloud.js';
+export {traversePointCloudSource} from './point-cloud-source.js';
+export type {PointCloudSourceTile, TraversePointCloudSourceOptions} from './point-cloud-source.js';
+export {encodePointCloudSource, encodePointCloudSourceTile} from './point-cloud-source-encoder.js';
+export type {
+  EncodedPointCloudSourceTile,
+  EncodePointCloudSourceOptions
+} from './point-cloud-source-encoder.js';
+export {convertPointCloudSource} from './point-cloud-conversion.js';
+export type {ConvertPointCloudSourceOptions} from './point-cloud-conversion.js';
+export type {
+  BrowserTilesetConversionInputResource,
+  BrowserTilesetConversionInspection,
+  BrowserTilesetConversionSourceOptions,
+  BrowserTilesetResourceDescriptor
+} from './browser-tileset-source.js';

package/src/v5/conversion-api.ts

@@ -0,0 +1,287 @@
+/** A diagnostic produced while inspecting, converting, or validating tiles. */
+export interface TileConversionDiagnostic {
+  /** Stable machine-readable diagnostic code. */
+  readonly code: string;
+  /** Human-readable explanation of the diagnostic. */
+  readonly message: string;
+  /** Severity used by callers to decide whether the result is acceptable. */
+  readonly severity: 'info' | 'warning' | 'error';
+  /** Optional resource that produced the diagnostic. */
+  readonly resourceId?: string;
+}
+
+/** Typed failure raised when a conversion policy or validation gate rejects a resource. */
+export class TileConversionError extends Error {
+  /** Stable machine-readable failure code. */
+  readonly code: string;
+  /** Diagnostics associated with this failure. */
+  readonly diagnostics: readonly TileConversionDiagnostic[];
+
+  /** Creates a typed conversion failure. */
+  constructor(
+    code: string,
+    message: string,
+    diagnostics: readonly TileConversionDiagnostic[] = []
+  ) {
+    super(message);
+    this.name = 'TileConversionError';
+    this.code = code;
+    this.diagnostics = diagnostics;
+  }
+}
+
+/** Progress reported by the portable conversion core. */
+export interface TileConversionProgress {
+  /** Current conversion phase. */
+  readonly phase: 'inspect' | 'convert' | 'validate' | 'finalize';
+  /** Number of input resources consumed so far. */
+  readonly inputResources: number;
+  /** Number of output resources written so far. */
+  readonly outputResources: number;
+  /** Number of input bytes consumed so far. */
+  readonly inputBytes: number;
+  /** Number of output bytes written so far. */
+  readonly outputBytes: number;
+}
+
+/** Summary returned after a tileset conversion completes. */
+export interface TileConversionReport {
+  /** Completed conversion state. Failed conversions reject with their cause. */
+  readonly state: 'completed';
+  /** Number of input resources consumed. */
+  readonly inputResources: number;
+  /** Number of output resources written. */
+  readonly outputResources: number;
+  /** Number of input bytes consumed. */
+  readonly inputBytes: number;
+  /** Number of output bytes written. */
+  readonly outputBytes: number;
+  /** Largest output resource written. */
+  readonly largestOutputResourceBytes: number;
+  /** Diagnostics reported during conversion and validation. */
+  readonly diagnostics: readonly TileConversionDiagnostic[];
+}
+
+/** Portable source adapter that resolves and reads a tileset. */
+export interface TileConversionSource<TInspection, TInput> {
+  /** Inspect the source and return its profile-specific metadata. */
+  inspect(signal?: AbortSignal): Promise<TInspection>;
+  /** Stream input resources in deterministic traversal order. */
+  read(inspection: TInspection, signal?: AbortSignal): AsyncIterable<TInput>;
+}
+
+/** Output adapter whose awaited writes apply backpressure to conversion. */
+export interface TileConversionSink<TOutput> {
+  /** Write one completed output resource and resolve when it can be released. */
+  write(resource: TOutput, signal?: AbortSignal): Promise<void>;
+  /** Finalize the destination after every resource has been written. */
+  finalize(report: TileConversionReport): Promise<void>;
+  /** Abort and clean up a partial destination after a failure. */
+  abort(reason: unknown): Promise<void>;
+}
+
+/** Codec adapter used to convert one input resource into streamed outputs. */
+export interface TileConversionCodec<TInspection, TInput, TOutput> {
+  /** Convert one input resource into zero or more output resources. */
+  convert(
+    resource: TInput,
+    inspection: TInspection,
+    signal?: AbortSignal
+  ): AsyncIterable<TOutput> | Promise<AsyncIterable<TOutput>>;
+  /** Optionally validate each output resource before it is written. */
+  validateOutput?(
+    resource: TOutput,
+    signal?: AbortSignal
+  ): Promise<readonly TileConversionDiagnostic[]>;
+}
+
+/** Options for the portable `convertTileset` operation. */
+export interface ConvertTilesetOptions<TInspection, TInput, TOutput> {
+  /** Injected input resolver and resource reader. */
+  readonly source: TileConversionSource<TInspection, TInput>;
+  /** Injected output codec. */
+  readonly codec: TileConversionCodec<TInspection, TInput, TOutput>;
+  /** Injected destination writer. */
+  readonly sink: TileConversionSink<TOutput>;
+  /** Return the decoded input byte size as a nonnegative safe integer. */
+  readonly measureInputBytes: (resource: TInput) => number;
+  /** Return the byte size of an output resource. */
+  readonly measureOutputBytes: (resource: TOutput) => number;
+  /** Reject a decoded input resource above this byte limit before encoding. Defaults to no limit. */
+  readonly maxInputResourceBytes?: number;
+  /** Reject any output resource larger than this configured byte limit. */
+  readonly maxOutputResourceBytes?: number;
+  /** Cancel inspection, conversion, validation, or writes. */
+  readonly signal?: AbortSignal;
+  /** Receive progress updates after each resource transition. */
+  readonly onProgress?: (progress: TileConversionProgress) => void;
+}
+
+/** Options for a standalone tileset validation pass. */
+export interface ValidateTilesetOptions<TTileset> {
+  /** Tileset or conversion result to validate. */
+  readonly tileset: TTileset;
+  /** Injected profile-specific validator. */
+  readonly validate: (
+    tileset: TTileset,
+    signal?: AbortSignal
+  ) => Promise<readonly TileConversionDiagnostic[]>;
+  /** Cancel validation. */
+  readonly signal?: AbortSignal;
+}
+
+/** Result of validating a tileset. */
+export interface TileValidationReport {
+  /** False when at least one error diagnostic was reported. */
+  readonly valid: boolean;
+  /** Diagnostics returned by the injected validator. */
+  readonly diagnostics: readonly TileConversionDiagnostic[];
+}
+
+/** Inspects a tileset with an injected, platform-specific source adapter. */
+export async function inspectTileset<TInspection, TInput>(
+  source: TileConversionSource<TInspection, TInput>,
+  signal?: AbortSignal
+): Promise<TInspection> {
+  throwIfAborted(signal);
+  const inspection = await source.inspect(signal);
+  throwIfAborted(signal);
+  return inspection;
+}
+
+/**
+ * Converts a stream of tileset resources through injected source, codec, and sink adapters.
+ * Decoded inputs are measured and checked against `maxInputResourceBytes` before encoding.
+ * This does not limit source decoding allocations or content retained by a source.
+ * Writes are awaited one resource at a time, keeping queued output bytes bounded by the
+ * largest emitted resource and the configured `maxOutputResourceBytes` limit.
+ */
+export async function convertTileset<TInspection, TInput, TOutput>(
+  options: ConvertTilesetOptions<TInspection, TInput, TOutput>
+): Promise<TileConversionReport> {
+  const {
+    source,
+    codec,
+    sink,
+    measureInputBytes,
+    measureOutputBytes,
+    maxInputResourceBytes = Number.POSITIVE_INFINITY,
+    maxOutputResourceBytes = Number.POSITIVE_INFINITY,
+    signal,
+    onProgress
+  } = options;
+  let inputResources = 0;
+  let outputResources = 0;
+  let inputBytes = 0;
+  let outputBytes = 0;
+  let largestOutputResourceBytes = 0;
+  const diagnostics: TileConversionDiagnostic[] = [];
+  const reportProgress = (phase: TileConversionProgress['phase']): void => {
+    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'
+      );
+    }
+    reportProgress('inspect');
+    const inspection = await inspectTileset(source, signal);
+    for await (const inputResource of source.read(inspection, signal)) {
+      throwIfAborted(signal);
+      const inputResourceBytes = measureInputBytes(inputResource);
+      if (!Number.isSafeInteger(inputResourceBytes) || inputResourceBytes < 0) {
+        throw new TileConversionError(
+          'INVALID_INPUT_RESOURCE_SIZE',
+          'measureInputBytes must return a nonnegative safe integer'
+        );
+      }
+      if (inputResourceBytes > maxInputResourceBytes) {
+        throw new TileConversionError(
+          'INPUT_RESOURCE_TOO_LARGE',
+          `Input resource is ${inputResourceBytes} bytes, exceeding the configured limit of ${maxInputResourceBytes} bytes`
+        );
+      }
+      inputResources++;
+      inputBytes += inputResourceBytes;
+      reportProgress('convert');
+      const convertedResources = await codec.convert(inputResource, inspection, signal);
+      for await (const outputResource of convertedResources) {
+        throwIfAborted(signal);
+        reportProgress('validate');
+        const resourceDiagnostics = (await codec.validateOutput?.(outputResource, signal)) || [];
+        diagnostics.push(...resourceDiagnostics);
+        const outputResourceBytes = measureOutputBytes(outputResource);
+        largestOutputResourceBytes = Math.max(largestOutputResourceBytes, outputResourceBytes);
+        if (outputResourceBytes > maxOutputResourceBytes) {
+          throw new TileConversionError(
+            'OUTPUT_RESOURCE_TOO_LARGE',
+            `Output resource is ${outputResourceBytes} bytes, exceeding the configured limit of ${maxOutputResourceBytes} bytes`
+          );
+        }
+        if (resourceDiagnostics.some(diagnostic => diagnostic.severity === 'error')) {
+          throw new TileConversionError(
+            'OUTPUT_VALIDATION_FAILED',
+            'Output resource validation failed',
+            resourceDiagnostics
+          );
+        }
+        throwIfAborted(signal);
+        await sink.write(outputResource, signal);
+        throwIfAborted(signal);
+        outputResources++;
+        outputBytes += outputResourceBytes;
+        reportProgress('convert');
+      }
+    }
+
+    const report: TileConversionReport = {
+      state: 'completed',
+      inputResources,
+      outputResources,
+      inputBytes,
+      outputBytes,
+      largestOutputResourceBytes,
+      diagnostics
+    };
+    throwIfAborted(signal);
+    reportProgress('finalize');
+    await sink.finalize(report);
+    return report;
+  } catch (error) {
+    try {
+      await sink.abort(error);
+    } catch (abortError) {
+      throw new AggregateError(
+        [error, abortError],
+        'Conversion failed and the destination could not abort'
+      );
+    }
+    throw error;
+  }
+}
+
+/** Validates a tileset through an injected profile-specific validator. */
+export async function validateTileset<TTileset>(
+  options: ValidateTilesetOptions<TTileset>
+): Promise<TileValidationReport> {
+  throwIfAborted(options.signal);
+  const diagnostics = await options.validate(options.tileset, options.signal);
+  throwIfAborted(options.signal);
+  return {
+    valid: !diagnostics.some(diagnostic => diagnostic.severity === 'error'),
+    diagnostics
+  };
+}
+
+/** Throws the signal reason when a conversion operation has been cancelled. */
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
+  }
+}