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

package/src/v5/node-conversion.ts

@@ -0,0 +1,345 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {mkdir, open, rm, link, mkdtemp} from 'node:fs/promises';
+import {dirname, join, resolve} from 'node:path';
+import {convertTileset, TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {
+  BrowserTileConversionFile,
+  BrowserTilesetConversionInspection,
+  TileConversionReport
+} from '@loaders.gl/tile-converter/v5/core';
+import {
+  createSelectedMeshConversionSource,
+  measureMeshBytes,
+  SELECTED_MESH_LIMITS,
+  createMeshConversionCodec,
+  createI3SMeshConversionCodec,
+  createMeshTilesetSink,
+  createMeshHierarchyTilesetSink,
+  createI3SMeshSink,
+  encodeTileConversionArchiveInBatches
+} from '@loaders.gl/tile-converter/v5/adapters';
+import type {
+  I3SMeshSourceFeatureOptions,
+  MeshSourceFeatureOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+import {createNodeTilesetConversionSource} from './node-source.js';
+import {createNodeI3SConversionSource} from './node-i3s-source.js';
+import type {NodeTilesetConversionSourceOptions} from './node-source.js';
+
+/** Explicit targets for the initial bounded Node mesh profile. */
+export type NodeTileConversionOutputFormat = '3d-tiles' | '3tz' | 'slpk';
+
+/** Selected static mesh conversion with application-owned Node output. */
+export interface NodeTileConversionOptions
+  extends Omit<NodeTilesetConversionSourceOptions, 'format'> {
+  /** Explicit 3D Tiles, I3S layer or indexed archive source. */
+  readonly format?: '3d-tiles' | '3tz' | 'i3s' | 'slpk';
+  /** Explicit I3S attribute mapping, also supplied by the CLI feature-schema file. */
+  readonly i3sFeatures?: I3SMeshSourceFeatureOptions;
+  /** Required metric source error for I3S to 3D Tiles; no screen-size inference. */
+  readonly geometricError?: number;
+  /** Retain a complete explicit 3D Tiles tree, including inspected external documents in 3D Tiles/3TZ output. */
+  readonly preserveHierarchy?: boolean;
+  /** Authorizes IntegratedMesh to 3DObject output with a reported semantic warning. */
+  readonly integratedMeshPolicy?: 'as-3d-object';
+  /** One to 64 inspected content placement identifiers; no automatic all-content conversion. */
+  readonly resourceIds: readonly string[];
+  /** Explicit feature class/schema mapping, also supplied by the CLI feature-schema file. */
+  readonly features?: MeshSourceFeatureOptions;
+  /** Target mesh profile, independent of output filename. */
+  readonly outputFormat: NodeTileConversionOutputFormat;
+  /** New destination path; omitted for profile validation without writing. */
+  readonly output?: string;
+  /** Maximum retained files and, separately, archive bytes; at most 32 MiB. */
+  readonly maxOutputBytes?: number;
+}
+
+/** Runs the qualified browser mesh codecs with confined Node input and optional output. */
+export async function convertNodeTileset(
+  options: NodeTileConversionOptions
+): Promise<TileConversionReport> {
+  const signal = options.signal ?? new AbortController().signal;
+  const maxOutputBytes = options.maxOutputBytes ?? SELECTED_MESH_LIMITS.maxOutputBytes;
+  if (
+    !['3d-tiles', '3tz', 'slpk'].includes(options.outputFormat) ||
+    !Number.isSafeInteger(maxOutputBytes) ||
+    maxOutputBytes < 1 ||
+    maxOutputBytes > SELECTED_MESH_LIMITS.maxOutputBytes
+  )
+    throw new TileConversionError(
+      'INVALID_NODE_CONVERSION_OPTIONS',
+      'Select a supported output profile and a positive output budget at most 32 MiB'
+    );
+  const i3s = options.format === 'i3s' || options.format === 'slpk';
+  if (
+    (options.preserveHierarchy !== undefined && typeof options.preserveHierarchy !== 'boolean') ||
+    (options.preserveHierarchy && (i3s || options.outputFormat === 'slpk'))
+  )
+    throw new TileConversionError(
+      'MESH_HIERARCHY_UNSUPPORTED',
+      'Hierarchy preservation requires 3D Tiles/3TZ input and output'
+    );
+  if (
+    i3s &&
+    ((options.outputFormat !== 'slpk' && options.geometricError === undefined) ||
+      (options.geometricError !== undefined &&
+        (typeof options.geometricError !== 'number' ||
+          !Number.isFinite(options.geometricError) ||
+          options.geometricError < 0)))
+  )
+    throw new TileConversionError(
+      'MESH_GEOMETRIC_ERROR_INVALID',
+      'I3S to 3D Tiles requires an explicit nonnegative geometric error in meters'
+    );
+  if (
+    i3s
+      ? options.features !== undefined
+      : options.i3sFeatures !== undefined ||
+        options.integratedMeshPolicy !== undefined ||
+        options.geometricError !== undefined
+  )
+    throw new TileConversionError(
+      'INVALID_NODE_CONVERSION_OPTIONS',
+      'Feature and layer policies must match the selected input format'
+    );
+  const sourceOptions = {
+    ...options,
+    signal,
+    inspectNestedTilesets: true,
+    maxTilesetDocuments: options.maxTilesetDocuments ?? SELECTED_MESH_LIMITS.maxTilesetDocuments
+  };
+  const rawSource = i3s
+    ? await createNodeI3SConversionSource({
+        ...sourceOptions,
+        format: options.format as 'i3s' | 'slpk'
+      })
+    : await createNodeTilesetConversionSource({
+        ...sourceOptions,
+        format: options.format as '3d-tiles' | '3tz' | undefined
+      });
+  let files: readonly BrowserTileConversionFile[];
+  let report: TileConversionReport;
+  try {
+    const inspection = await rawSource.inspect(signal);
+    await import('@loaders.gl/polyfills');
+    const {getDracoLibraryOptions} = await import('@loaders.gl/draco/bundled');
+    const dracoLibraryOptions = getDracoLibraryOptions({
+      decoderProfile: 'full',
+      useLocalLibraries: true
+    });
+    const selection =
+      'select' in rawSource
+        ? {
+            ...(await rawSource.select(
+              inspection as Awaited<ReturnType<typeof rawSource.inspect>>,
+              options.resourceIds,
+              dracoLibraryOptions,
+              options.i3sFeatures
+            )),
+            geometricError: (options.geometricError ?? 0) + SELECTED_MESH_LIMITS.maxPositionError
+          }
+        : await createSelectedMeshConversionSource(
+            inspection as Awaited<ReturnType<typeof rawSource.inspect>>,
+            {
+              resourceIds: options.resourceIds,
+              preserveHierarchy: options.preserveHierarchy,
+              features: options.features,
+              signal,
+              source: rawSource,
+              fetcher: rawSource.fetcher,
+              dracoLibraryOptions,
+              maxInputBytes: options.maxInputBytes
+            }
+          );
+    const {source, spatialContext, geometricError} = selection;
+    const common = {
+      source,
+      signal,
+      measureInputBytes: measureMeshBytes,
+      maxInputBytes: options.maxInputBytes ?? SELECTED_MESH_LIMITS.maxInputBytes,
+      maxOutputBytes,
+      maxInputResources: SELECTED_MESH_LIMITS.maxMeshResources,
+      maxOutputResources: SELECTED_MESH_LIMITS.maxMeshResources
+    };
+    const codecOptions = {
+      spatialContext,
+      autoOrigin: i3s,
+      integratedMeshPolicy: options.integratedMeshPolicy,
+      dracoLibraryOptions,
+      maxPositionError: SELECTED_MESH_LIMITS.maxPositionError
+    };
+    if (options.outputFormat === 'slpk') {
+      const sink = createI3SMeshSink({
+        maxTotalBytes: maxOutputBytes,
+        maxMeshes: SELECTED_MESH_LIMITS.maxMeshResources,
+        maxResourceBytes: maxOutputBytes
+      });
+      report = await convertTileset({
+        ...common,
+        sink,
+        codec: createI3SMeshConversionCodec({...codecOptions, maxResourceBytes: maxOutputBytes}),
+        measureOutputBytes: resource =>
+          Object.values(resource.files).reduce((total, bytes) => total + bytes.byteLength, 0)
+      });
+      files = sink.getFiles();
+    } else {
+      const sink = options.preserveHierarchy
+        ? createMeshHierarchyTilesetSink({
+            inspection: inspection as BrowserTilesetConversionInspection,
+            resourceIds: options.resourceIds,
+            maxTotalBytes: maxOutputBytes,
+            maxPositionError: SELECTED_MESH_LIMITS.maxPositionError
+          })
+        : createMeshTilesetSink({
+            maxTotalBytes: maxOutputBytes,
+            maxMeshes: SELECTED_MESH_LIMITS.maxMeshResources,
+            geometricError
+          });
+      report = await convertTileset({
+        ...common,
+        sink,
+        codec: createMeshConversionCodec(codecOptions),
+        measureOutputBytes: resource => resource.glb.byteLength
+      });
+      files = sink.getFiles();
+    }
+  } finally {
+    await rawSource.close();
+  }
+  signal.throwIfAborted();
+  // Validate packaging as well as content, including on the write-free validation path.
+  if (options.outputFormat !== '3d-tiles' && !options.output) {
+    for await (const chunk of encodeTileConversionArchiveInBatches(files, {
+      format: options.outputFormat,
+      maxArchiveBytes: maxOutputBytes,
+      signal
+    }))
+      void chunk;
+  }
+  if (options.output)
+    await writeNodeTileConversionOutput(
+      files,
+      options.output,
+      options.outputFormat,
+      maxOutputBytes,
+      signal
+    );
+  return report;
+}
+
+/** Saves fixed relative resource names or an archive; existing destinations are never overwritten. */
+export async function writeNodeTileConversionOutput(
+  files: readonly BrowserTileConversionFile[],
+  output: string,
+  format: NodeTileConversionOutputFormat,
+  maxOutputBytes: number,
+  signal: AbortSignal
+): Promise<void> {
+  signal.throwIfAborted();
+  if (
+    !['3d-tiles', '3tz', 'slpk'].includes(format) ||
+    !Number.isSafeInteger(maxOutputBytes) ||
+    maxOutputBytes < 1
+  )
+    throw new TileConversionError(
+      'INVALID_NODE_OUTPUT',
+      'Output requires a supported format and positive safe byte limit'
+    );
+  let bytes = 0;
+  const names = new Set<string>();
+  for (const file of files) {
+    const name = file.resourceId;
+    if (
+      !name ||
+      name.includes('\\') ||
+      name.includes('\0') ||
+      name.includes(':') ||
+      name.split('/').some(segment => !segment || segment === '.' || segment === '..') ||
+      names.has(name)
+    )
+      throw new TileConversionError(
+        'INVALID_NODE_OUTPUT',
+        'Output names must be unique confined relative resource paths'
+      );
+    names.add(name);
+    if (file.blob.size > maxOutputBytes - bytes)
+      throw new TileConversionError(
+        'OUTPUT_BYTES_LIMIT_EXCEEDED',
+        'Output files exceed the byte budget'
+      );
+    bytes += file.blob.size;
+  }
+  const destination = resolve(output);
+  if (format === '3d-tiles') {
+    // Exclusive directory creation makes every subsequently created child application-owned.
+    await mkdir(destination);
+    try {
+      for (const file of files) {
+        signal.throwIfAborted();
+        const path = join(destination, file.resourceId);
+        await mkdir(dirname(path), {recursive: true});
+        const handle = await open(path, 'wx');
+        try {
+          const reader = file.blob.stream().getReader();
+          try {
+            while (true) {
+              signal.throwIfAborted();
+              const {value, done} = await reader.read();
+              if (done) break;
+              await writeFileBytes(handle, value, signal);
+            }
+          } finally {
+            await reader.cancel();
+            reader.releaseLock();
+          }
+        } finally {
+          await handle.close();
+        }
+      }
+      signal.throwIfAborted();
+    } catch (error) {
+      await rm(destination, {recursive: true, force: true});
+      throw error;
+    }
+  } else {
+    const temporaryDirectory = await mkdtemp(join(dirname(destination), '.tile-converter-'));
+    try {
+      const path = join(temporaryDirectory, 'archive');
+      const handle = await open(path, 'wx');
+      try {
+        for await (const chunk of encodeTileConversionArchiveInBatches(files, {
+          format,
+          maxArchiveBytes: maxOutputBytes,
+          signal
+        }))
+          await writeFileBytes(handle, chunk, signal);
+      } finally {
+        await handle.close();
+      }
+      signal.throwIfAborted();
+      // Same-filesystem hard link publishes a complete archive and fails if the destination exists.
+      await link(path, destination);
+    } finally {
+      await rm(temporaryDirectory, {recursive: true, force: true});
+    }
+  }
+}
+
+/** Completes native typed-array writes, including partial writes and cooperative cancellation. */
+async function writeFileBytes(
+  handle: Awaited<ReturnType<typeof open>>,
+  bytes: Uint8Array,
+  signal: AbortSignal
+): Promise<void> {
+  let offset = 0;
+  while (offset < bytes.byteLength) {
+    signal.throwIfAborted();
+    const result = await handle.write(bytes, offset, bytes.byteLength - offset);
+    if (!result.bytesWritten)
+      throw new TileConversionError('NODE_OUTPUT_WRITE_FAILED', 'Output write made no progress');
+    offset += result.bytesWritten;
+  }
+}

package/src/v5/node-feature-schema.ts

@@ -0,0 +1,155 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {constants} from 'node:fs';
+import {open} from 'node:fs/promises';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import type {NodeTileConversionOptions} from './node-conversion.js';
+
+/** Maximum bytes retained for a local declarative feature mapping. */
+const MAXIMUM_SCHEMA_BYTES = 64 * 1024;
+/** Scalar storage types shared by the qualified mesh feature readers and writers. */
+const FIELD_TYPES = [
+  'int8',
+  'uint8',
+  'int16',
+  'uint16',
+  'int32',
+  'uint32',
+  'int64',
+  'uint64',
+  'float32',
+  'float64',
+  'utf8'
+];
+
+/** Reads a bounded local JSON mapping; source/destination adapters validate data semantics. */
+export async function readFeatureSchema(
+  path: string,
+  i3s: boolean,
+  signal?: AbortSignal
+): Promise<Pick<NodeTileConversionOptions, 'features' | 'i3sFeatures'>> {
+  signal?.throwIfAborted();
+  // Avoid blocking on special files before the regular-file check.
+  const file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  let mapping: unknown;
+  try {
+    if (!(await file.stat()).isFile()) rejectSchema('Feature schema must be a regular local file');
+    const bytes = new Uint8Array(MAXIMUM_SCHEMA_BYTES + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      signal?.throwIfAborted();
+      const {bytesRead} = await file.read(bytes, length, bytes.length - length, null);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    signal?.throwIfAborted();
+    if (length > MAXIMUM_SCHEMA_BYTES) rejectSchema('Feature schema exceeds 64 KiB');
+    try {
+      mapping = JSON.parse(
+        new TextDecoder('utf-8', {fatal: true}).decode(bytes.subarray(0, length))
+      );
+    } catch {
+      rejectSchema('Feature schema must contain valid UTF-8 JSON');
+    }
+  } finally {
+    await file.close();
+  }
+  const options = requireRecord(mapping);
+  rejectUnknownKeys(options, [
+    'schema',
+    'metadataClass',
+    'sourceFeatureIdProperty',
+    'featureIdField',
+    'batchSize',
+    'integer64Encoding',
+    ...(i3s ? ['objectIdProperty', 'maxAttributeBytes'] : [])
+  ]);
+  requireName(options.metadataClass);
+  for (const key of ['sourceFeatureIdProperty', 'featureIdField']) {
+    if (options[key] !== undefined) requireName(options[key]);
+  }
+  if (
+    options.batchSize !== undefined &&
+    (!Number.isSafeInteger(options.batchSize) ||
+      Number(options.batchSize) < 1 ||
+      Number(options.batchSize) > 65536)
+  )
+    rejectSchema('batchSize must be an integer from 1 to 65536');
+  if (options.integer64Encoding !== undefined && options.integer64Encoding !== 'decimal-string')
+    rejectSchema('integer64Encoding must be decimal-string when supplied');
+  const schema = requireRecord(options.schema);
+  rejectUnknownKeys(schema, ['fields', 'metadata']);
+  validateMetadata(schema.metadata);
+  if (!Array.isArray(schema.fields) || !schema.fields.length || schema.fields.length > 256)
+    rejectSchema('schema.fields must declare between 1 and 256 fields');
+  const names = new Set<string>();
+  for (const value of schema.fields) {
+    const field = requireRecord(value);
+    rejectUnknownKeys(field, ['name', 'type', 'nullable', 'metadata']);
+    requireName(field.name);
+    if (names.has(field.name as string)) rejectSchema('Feature fields must have unique names');
+    names.add(field.name as string);
+    if (
+      typeof field.type !== 'string' ||
+      !FIELD_TYPES.includes(field.type) ||
+      (field.nullable !== undefined && typeof field.nullable !== 'boolean')
+    )
+      rejectSchema('Fields require a scalar numeric/utf8 type and an optional boolean nullable');
+    validateMetadata(field.metadata);
+  }
+  const identifier = schema.fields.find(
+    value => value.name === (options.featureIdField ?? 'feature_id')
+  );
+  if (
+    !identifier ||
+    identifier.nullable === true ||
+    !['utf8', ...FIELD_TYPES.filter(type => /^(u?int)/.test(type))].includes(identifier.type)
+  )
+    rejectSchema('Declare a nonnullable string or integer feature ID field');
+  if (i3s) {
+    requireName(options.objectIdProperty);
+    if (
+      !Number.isSafeInteger(options.maxAttributeBytes) ||
+      Number(options.maxAttributeBytes) < 1 ||
+      Number(options.maxAttributeBytes) > 16 * 1024 * 1024
+    )
+      rejectSchema('maxAttributeBytes must be a positive integer at most 16 MiB');
+    return {
+      i3sFeatures: options as unknown as NonNullable<NodeTileConversionOptions['i3sFeatures']>
+    };
+  }
+  return {features: options as unknown as NonNullable<NodeTileConversionOptions['features']>};
+}
+
+/** Rejects unknown configuration keys rather than silently ignoring misspelled controls. */
+function rejectUnknownKeys(record: Record<string, unknown>, allowed: readonly string[]): void {
+  if (Object.keys(record).some(key => !allowed.includes(key)))
+    rejectSchema('Unknown feature-schema option');
+}
+
+/** Requires a JSON object before accessing its fields. */
+function requireRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    rejectSchema('Feature mappings require JSON objects');
+  return value as Record<string, unknown>;
+}
+
+/** Requires a nonempty class, property or column name. */
+function requireName(value: unknown): void {
+  if (typeof value !== 'string' || !value.trim())
+    rejectSchema('Feature names must be nonempty strings');
+}
+
+/** Retains only string-valued schema/field metadata. */
+function validateMetadata(value: unknown): void {
+  if (value === undefined) return;
+  if (Object.values(requireRecord(value)).some(entry => typeof entry !== 'string'))
+    rejectSchema('Schema metadata values must be strings');
+}
+
+/** Reports configuration failures before source conversion or output publication. */
+function rejectSchema(message: string): never {
+  throw new TileConversionError('CLI_FEATURE_SCHEMA_INVALID', message);
+}

package/src/v5/node-i3s-source.ts

@@ -0,0 +1,181 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {realpath} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import {resolve} from 'node:path';
+import {TileConversionError} from '@loaders.gl/tile-converter/v5/core';
+import {
+  createSelectedI3SMeshConversionSource,
+  inspectI3SMeshConversionSource,
+  createTileConversionArchiveTransport,
+  openTileConversionArchive
+} from '@loaders.gl/tile-converter/v5/adapters';
+import type {
+  I3SMeshSelectionOptions,
+  I3SMeshSourceFeatureOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+import {createTileConversionResourceFetcher} from './resource-fetcher.js';
+import {NODE_TILESET_LIMITS, openLocalFile} from './node-source.js';
+import type {NodeTilesetConversionSourceOptions} from './node-source.js';
+
+/** Bounded I3S layer URL or indexed SLPK input with application-owned transport. */
+export interface NodeI3SConversionSourceOptions
+  extends Omit<NodeTilesetConversionSourceOptions, 'format' | 'inspectNestedTilesets'> {
+  /** I3S HTTP(S) layer or local/HTTP(S) SLPK archive. */
+  readonly format: 'i3s' | 'slpk';
+}
+
+/** Opens one lifetime-budgeted I3S source; its owner must close it in finally. */
+export async function createNodeI3SConversionSource(options: NodeI3SConversionSourceOptions) {
+  const maxInputBytes = options.maxInputBytes ?? NODE_TILESET_LIMITS.maxInputBytes;
+  const maxInputResources = options.maxInputResources ?? NODE_TILESET_LIMITS.maxInputResources;
+  if (
+    !['i3s', 'slpk'].includes(options.format) ||
+    !Number.isSafeInteger(maxInputBytes) ||
+    maxInputBytes < 1 ||
+    maxInputBytes > NODE_TILESET_LIMITS.maxInputBytes ||
+    !Number.isSafeInteger(maxInputResources) ||
+    maxInputResources < 1 ||
+    maxInputResources > NODE_TILESET_LIMITS.maxInputResources
+  )
+    throw new TileConversionError(
+      'INVALID_NODE_SOURCE_OPTIONS',
+      'I3S sources require positive budgets within the bounded input profile'
+    );
+  const controller = new AbortController();
+  const signal = options.signal
+    ? AbortSignal.any([options.signal, controller.signal])
+    : controller.signal;
+  signal.throwIfAborted();
+  let release: (() => Promise<void>) | undefined;
+  let closePromise: Promise<void> | undefined;
+  /** Cancels cached/runtime work and releases owned indexed readers exactly once. */
+  const close = async (): Promise<void> => {
+    controller.abort(new TileConversionError('NODE_SOURCE_CLOSED', 'Node source is closed'));
+    closePromise ??= release?.() ?? Promise.resolve();
+    await closePromise;
+  };
+  try {
+    const remote = /^https?:/i.test(options.input);
+    if (options.format === 'i3s' && !remote)
+      throw new TileConversionError(
+        'UNSUPPORTED_NODE_SOURCE',
+        'I3S input requires an HTTP(S) layer URL; use slpk for a local archive'
+      );
+    let rootUrl: string;
+    let transport: typeof fetch;
+    if (options.format === 'slpk') {
+      const archive = remote
+        ? await openTileConversionArchive(
+            {input: options.input, format: 'slpk'},
+            maxInputBytes,
+            signal,
+            options.fetcher
+          )
+        : await createTileConversionArchiveTransport(
+            await openLocalFile(
+              await realpath(
+                /^file:/i.test(options.input)
+                  ? fileURLToPath(options.input)
+                  : resolve(options.input)
+              ),
+              maxInputBytes,
+              signal,
+              () => {}
+            ),
+            'slpk',
+            maxInputBytes,
+            signal
+          );
+      release = archive.close;
+      rootUrl = archive.rootUrl;
+      transport = archive.fetcher;
+    } else {
+      rootUrl = new URL(options.input).href;
+      transport = options.fetcher ?? fetch;
+    }
+    const bounded = createTileConversionResourceFetcher({
+      maxInputBytes,
+      signal,
+      fetcher: transport
+    });
+    let metadataBytes = 0;
+    const root = new URL(rootUrl);
+    /** Inherits query credentials only within the selected layer's origin and path. */
+    const fetcher: typeof fetch = async (input, requestOptions) => {
+      const url = new URL(input instanceof Request ? input.url : String(input));
+      if (
+        url.origin === root.origin &&
+        (url.pathname === root.pathname || url.pathname.startsWith(`${root.pathname}/`))
+      )
+        for (const [key, value] of root.searchParams)
+          if (!url.searchParams.has(key)) url.searchParams.set(key, value);
+      const response = await bounded(
+        input instanceof Request ? new Request(url, input) : url,
+        requestOptions
+      );
+      if (response.url && response.url !== url.href)
+        throw new TileConversionError(
+          'I3S_REDIRECT_UNSUPPORTED',
+          'Use the final I3S resource URL; redirected resource bases are not qualified'
+        );
+      const bytes = await response.arrayBuffer();
+      metadataBytes += bytes.byteLength;
+      const result = new Response(bytes, {status: response.status, headers: response.headers});
+      Object.defineProperty(result, 'url', {value: response.url});
+      return result;
+    };
+    // Metadata inspection needs no decoder transport initialization. Conversion injects bundled assets.
+    const selectionOptions: I3SMeshSelectionOptions = {
+      rootUrl,
+      fetcher,
+      signal,
+      maxInputBytes,
+      maxInputResources,
+      dracoLibraryOptions: {decoderProfile: 'full' as const}
+    };
+    return {
+      close,
+      /** Reads only layer and node metadata, under the same lifetime-wide budget as conversion. */
+      async inspect(operationSignal?: AbortSignal) {
+        signal.throwIfAborted();
+        operationSignal?.throwIfAborted();
+        const activeSignal = operationSignal ? AbortSignal.any([signal, operationSignal]) : signal;
+        /** Forwards borrowed operation cancellation without closing the owning source. */
+        const operationFetcher: typeof fetch = (input, requestOptions) =>
+          fetcher(input, {
+            ...requestOptions,
+            signal: requestOptions?.signal
+              ? AbortSignal.any([activeSignal, requestOptions.signal])
+              : activeSignal
+          });
+        const inspection = await inspectI3SMeshConversionSource({
+          ...selectionOptions,
+          fetcher: operationFetcher,
+          signal: activeSignal
+        });
+        return {...inspection, metadataBytes};
+      },
+      /** Creates an original-coordinate selected mesh source using application-provided Draco assets. */
+      select: (
+        inspection: Awaited<ReturnType<typeof inspectI3SMeshConversionSource>>,
+        resourceIds: readonly string[],
+        dracoLibraryOptions: I3SMeshSelectionOptions['dracoLibraryOptions'],
+        features?: I3SMeshSourceFeatureOptions
+      ) => {
+        signal.throwIfAborted();
+        return createSelectedI3SMeshConversionSource(inspection, {
+          ...selectionOptions,
+          resourceIds,
+          dracoLibraryOptions,
+          features
+        });
+      }
+    };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}