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

package/src/v5/conversion-api.ts

@@ -111,6 +111,14 @@ export interface ConvertTilesetOptions<TInspection, TInput, TOutput> {
   readonly maxInputResourceBytes?: number;
   /** Reject any output resource larger than this configured byte limit. */
   readonly maxOutputResourceBytes?: number;
+  /** Maximum measured input bytes across this run; does not bound source allocations. */
+  readonly maxInputBytes?: number;
+  /** Maximum measured output bytes across this run, including checkpointed resources. */
+  readonly maxOutputBytes?: number;
+  /** Maximum input resources consumed by this run, including zero-byte resources. */
+  readonly maxInputResources?: number;
+  /** Maximum outputs processed by this run, including zero-byte and checkpointed resources. */
+  readonly maxOutputResources?: number;
   /** Cancel inspection, conversion, validation, or writes. */
   readonly signal?: AbortSignal;
   /** Receive progress updates after each resource transition. */
@@ -155,6 +163,7 @@ export async function inspectTileset<TInspection, TInput>(
  * 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.
+ * Cumulative byte/count limits bound measured work in this run, not total allocation memory.
  */
 export async function convertTileset<TInspection, TInput, TOutput>(
   options: ConvertTilesetOptions<TInspection, TInput, TOutput>
@@ -167,6 +176,10 @@ export async function convertTileset<TInspection, TInput, TOutput>(
     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;
@@ -181,19 +194,26 @@ export async function convertTileset<TInspection, TInput, TOutput>(
   };
 
   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']
+    ] as const) {
+      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)) {
       throwIfAborted(signal);
+      checkConversionTotal(inputResources, 1, maxInputResources, 'INPUT_COUNT_LIMIT_EXCEEDED');
       const inputResourceBytes = measureInputBytes(inputResource);
       if (!Number.isSafeInteger(inputResourceBytes) || inputResourceBytes < 0) {
         throw new TileConversionError(
@@ -207,23 +227,41 @@ export async function convertTileset<TInspection, TInput, TOutput>(
           `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) {
         throwIfAborted(signal);
+        checkConversionTotal(outputResources, 1, maxOutputResources, 'OUTPUT_COUNT_LIMIT_EXCEEDED');
         reportProgress('validate');
         const resourceDiagnostics = (await 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',
@@ -234,6 +272,7 @@ export async function convertTileset<TInspection, TInput, TOutput>(
         throwIfAborted(signal);
         await sink.write(outputResource, signal);
         throwIfAborted(signal);
+        largestOutputResourceBytes = Math.max(largestOutputResourceBytes, outputResourceBytes);
         outputResources++;
         outputBytes += outputResourceBytes;
         reportProgress('convert');
@@ -285,3 +324,24 @@ function throwIfAborted(signal?: AbortSignal): void {
     throw signal.reason ?? new DOMException('The operation was aborted', 'AbortError');
   }
 }
+
+/** Checks a cumulative budget without overflowing safe integer accounting. */
+function checkConversionTotal(
+  current: number,
+  increment: number,
+  limit: number,
+  code: string
+): void {
+  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'
+    );
+  }
+}

package/src/v5/converter-cli.ts

@@ -0,0 +1,28 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {runTileConverterCLI} from './node-cli.js';
+
+/** Runs the Node process adapter and maps SIGINT into cooperative I/O cancellation. */
+async function main(): Promise<void> {
+  const controller = new AbortController();
+  /** Cancels the active operation; promise cleanup closes source and output handles. */
+  const cancelOperation = (): void =>
+    controller.abort(new Error('Tile conversion operation interrupted'));
+  process.on('SIGINT', cancelOperation);
+  try {
+    process.exitCode = await runTileConverterCLI(
+      process.argv.slice(2),
+      {
+        stdout: text => process.stdout.write(text),
+        stderr: text => process.stderr.write(text)
+      },
+      controller.signal
+    );
+  } finally {
+    process.removeListener('SIGINT', cancelOperation);
+  }
+}
+
+void main();

package/src/v5/core.ts

@@ -59,3 +59,9 @@ export type {
   BrowserTilesetResourceDescriptor,
   BrowserTilesetConversionInputResource
 } from './browser-tileset-source.js';
+
+export {selectBrowserTilesetContent} from './browser-tileset-source.js';
+export type {
+  BrowserTilesetDocumentPlacement,
+  BrowserTilesetContentSelection
+} from './browser-tileset-source.js';

package/src/v5/i3s-mesh-conversion.ts

@@ -2,7 +2,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {encodeI3SMeshLayer, encodeI3SMeshLayerWithDraco} from '@loaders.gl/i3s';
+import {
+  encodeI3SMeshLayer,
+  encodeI3SMeshLayerWithDraco,
+  preloadI3SMeshCompression
+} from '@loaders.gl/i3s';
 import type {
   EncodedI3SMeshLayer,
   I3SMeshWriterOptions,
@@ -23,6 +27,8 @@ import type {BrowserTileConversionFile} from '@loaders.gl/tile-converter/v5/core
 export interface I3SMeshConversionResource extends EncodedI3SMeshLayer {
   /** Source placement identifier used for diagnostics. */
   readonly id: string;
+  /** Original I3S layer type when authoring from an I3S source. */
+  readonly sourceLayerType?: '3DObject' | 'IntegratedMesh';
 }
 
 /** Spatial preparation and required authoring limits for the I3S codec. */
@@ -34,6 +40,8 @@ export interface I3SMeshConversionCodecOptions
   readonly normalReferenceFrame?: 'earth-centered' | 'vertex-reference-frame';
   /** Lossless Edge Breaker geometry by default; false retains raw I3S geometry. */
   readonly draco?: boolean;
+  /** Explicitly authorize IntegratedMesh input to become 3DObject output; omission rejects it. */
+  readonly integratedMeshPolicy?: 'as-3d-object';
   /** Full Draco encoder/decoder runtime URLs or injected modules. */
   readonly dracoLibraryOptions?: I3SDracoLibraryOptions;
 }
@@ -42,6 +50,15 @@ export interface I3SMeshConversionCodecOptions
 export function createI3SMeshConversionCodec<TInspection = unknown>(
   options: I3SMeshConversionCodecOptions
 ): TileConversionCodec<TInspection, MeshSourceResource, I3SMeshConversionResource> {
+  if (
+    options.integratedMeshPolicy !== undefined &&
+    options.integratedMeshPolicy !== 'as-3d-object'
+  ) {
+    throw new TileConversionError(
+      'I3S_LAYER_TYPE_POLICY_INVALID',
+      'Unknown IntegratedMesh conversion policy'
+    );
+  }
   const reference = options.spatialContext.spatialReference;
   const height =
     reference.targetHeightReference === 'native'
@@ -65,6 +82,15 @@ export function createI3SMeshConversionCodec<TInspection = unknown>(
     /** Places a source mesh in ECEF and authors one layer without modifying source arrays. */
     async *convert(resource, _inspection, signal) {
       signal?.throwIfAborted();
+      if (
+        resource.sourceLayerType === 'IntegratedMesh' &&
+        options.integratedMeshPolicy !== 'as-3d-object'
+      ) {
+        throw new TileConversionError(
+          'I3S_LAYER_TYPE_CHANGE_REQUIRED',
+          'IntegratedMesh to 3DObject conversion requires integratedMeshPolicy=as-3d-object'
+        );
+      }
       const mesh = validateMeshGeometry(resource.mesh, true);
       const positions = mesh.attributes.POSITION.value;
       const context = options.spatialContext;
@@ -86,6 +112,7 @@ export function createI3SMeshConversionCodec<TInspection = unknown>(
       if (mesh.attributes.NORMAL) mesh.attributes.NORMAL = {value: transformed.normals!, size: 3};
       let layer: EncodedI3SMeshLayer;
       try {
+        await preloadI3SMeshCompression();
         const writerOptions = {
           ...options,
           material: resource.material,
@@ -105,11 +132,22 @@ export function createI3SMeshConversionCodec<TInspection = unknown>(
       signal?.throwIfAborted();
       objectIdOffset +=
         resource.features?.batches.reduce((total, batch) => total + batch.data.numRows, 0) ?? 1;
-      yield {id: resource.id, ...layer};
+      yield {id: resource.id, ...layer, sourceLayerType: resource.sourceLayerType};
     },
     /** Reports measured precision and explicitly authorized integer representation changes. */
     async validateOutput(resource) {
       return [
+        ...(resource.sourceLayerType === 'IntegratedMesh'
+          ? [
+              {
+                code: 'I3S_LAYER_TYPE_CHANGED',
+                message:
+                  'Explicitly authored IntegratedMesh geometry as I3S 1.7 3DObject; integrated surface layer semantics and source LOD are not preserved',
+                severity: 'warning' as const,
+                resourceId: resource.id
+              }
+            ]
+          : []),
         ...(resource.maximumPositionError > 0
           ? [
               {

package/src/v5/i3s-mesh-sink.ts

@@ -113,7 +113,7 @@ export function createI3SMeshSink(options: I3SMeshSinkOptions): I3SMeshSink {
       'I3S collections require 1–64 meshes and a positive resource byte limit'
     );
   const memory = createBoundedMemoryTileConversionSink(options);
-  const compressor = new GZipCompressor({useNative: false, gzip: {mtime: 0}});
+  const compressor = new GZipCompressor({useNative: false});
   const decompressor = new GZipDecompressor({useNative: false});
   const leaves: {node: MeshNode; legacy: Record<string, unknown>}[] = [];
   const identifiers = new Set<string>();

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

@@ -212,6 +212,7 @@ export function createI3SMeshTilesetConversionSource(
           yield {
             id: `${item.tile.id}/${entry.index}`,
             origin: [0, 0, 0],
+            sourceLayerType: metadata.tileset.layerType,
             mesh,
             normalReferenceFrame:
               content.normalReferenceFrame === 'vertex-reference-frame'

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

@@ -0,0 +1,298 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {coreApi, parse} from '@loaders.gl/core';
+import {I3SLoader} from '@loaders.gl/i3s';
+import type {I3STileHeader, SceneLayer3D} from '@loaders.gl/i3s';
+import {I3SSource, Tileset3D} from '@loaders.gl/tiles';
+import type {TilesetSourceResolver} from '@loaders.gl/tiles';
+import {
+  createI3SConversionSpatialContext,
+  TileConversionError
+} from '@loaders.gl/tile-converter/v5/core';
+import {createI3SMeshTilesetConversionSource} from './i3s-mesh-source.js';
+import type {I3SMeshSourceFeatureOptions} from './i3s-mesh-source.js';
+import {SELECTED_MESH_LIMITS, measureMeshBytes} from './selected-mesh-source.js';
+import type {SelectedMeshSourceOptions} from './selected-mesh-source.js';
+
+/** Inspected leaf mesh identity and immutable normalized header. */
+export interface I3SMeshConversionResourceDescriptor {
+  /** Unique declared node identity. */
+  readonly resourceId: string;
+  /** Source-managed geometry URL. */
+  readonly uri: string;
+  /** Normalized header without runtime objects. */
+  readonly header: I3STileHeader;
+}
+
+/** Metadata-only I3S selection, independent of browser or Node transport ownership. */
+export interface I3SMeshConversionInspection {
+  /** Discriminant for I3S mesh input. */
+  readonly kind: 'i3s';
+  /** Absolute layer or archive virtual root URL. */
+  readonly rootUrl: string;
+  /** Original layer declarations. */
+  readonly layer: SceneLayer3D;
+  /** Ordered leaf mesh declarations. */
+  readonly resources: readonly I3SMeshConversionResourceDescriptor[];
+  /** Previously consumed transport bytes, supplied by the owner. */
+  readonly metadataBytes: number;
+}
+
+/** Platform-injected transport and decoder policy for bounded I3S selection. */
+export interface I3SMeshSelectionOptions {
+  /** Root layer or confined archive root URL. */
+  readonly rootUrl: string;
+  /** Lifetime-budgeted transport shared between metadata and payload reads. */
+  readonly fetcher: typeof fetch;
+  /** Operation cancellation. */
+  readonly signal: AbortSignal;
+  /** Bundled or application-owned Draco assets. */
+  readonly dracoLibraryOptions: SelectedMeshSourceOptions['dracoLibraryOptions'];
+  /** Maximum decoded mesh bytes; callers may lower the 16 MiB profile. */
+  readonly maxInputBytes?: number;
+  /** Maximum inspected nodes; callers may lower the 1,000 node profile. */
+  readonly maxInputResources?: number;
+}
+
+/** Creates a dedicated source-coordinate runtime with transport and all decoder assets injected. */
+function createRuntime(
+  transport: I3SMeshSelectionOptions,
+  layer?: SceneLayer3D,
+  header?: I3STileHeader
+): Tileset3D {
+  const libraries = transport.dracoLibraryOptions;
+  const sourceUrl = new URL(transport.rootUrl);
+  sourceUrl.search = '';
+  sourceUrl.hash = '';
+  const options = {
+    modules: libraries.modules,
+    core: {
+      worker: false,
+      fetch: transport.fetcher,
+      CDN: libraries.CDN,
+      useLocalLibraries: libraries.useLocalLibraries
+    },
+    draco: {decoderProfile: libraries.decoderProfile},
+    // The injected transport owns credential scope; runtime query parameters apply to every URL.
+    i3s: {geometryMode: 'source' as const, decodeTextures: false, useCompressedTextures: false}
+  };
+  /** Parses a source-managed resource with the same transport available to nested dependencies. */
+  const loadResource: TilesetSourceResolver['loadResource'] = async (url, loader, loadOptions) => {
+    const response = await transport.fetcher(url);
+    const contextUrl = new URL(url);
+    contextUrl.search = '';
+    contextUrl.hash = '';
+    return parse(await response.arrayBuffer(), loader, loadOptions, {
+      url: contextUrl.href,
+      fetch: transport.fetcher,
+      coreApi,
+      _parse: parse
+    });
+  };
+  const source = new I3SSource(
+    header && layer
+      ? {
+          ...layer,
+          root: {...header, children: []},
+          type: 'I3S',
+          url: sourceUrl.href,
+          basePath: sourceUrl.href,
+          loader: I3SLoader,
+          coreApi
+        }
+      : {
+          url: sourceUrl.href,
+          loader: I3SLoader,
+          coreApi,
+          resolver: {loadRoot: loadResource, loadResource}
+        },
+    options
+  );
+  // Preloaded selection still uses this resolver for content; never let core perform unbounded I/O.
+  source.coreApi = {...coreApi, load: loadResource as typeof coreApi.load};
+  return new Tileset3D(source, {i3s: options.i3s});
+}
+
+/** Inspects supported layer/leaf declarations without requesting geometry, textures or attributes. */
+export async function inspectI3SMeshConversionSource(
+  options: I3SMeshSelectionOptions
+): Promise<I3SMeshConversionInspection> {
+  const {signal} = options;
+  validateSelectionOptions(options);
+  signal.throwIfAborted();
+  const transport = options;
+  let runtime: Tileset3D | undefined;
+  try {
+    const response = await transport.fetcher(transport.rootUrl);
+    const layer = (await response.json()) as SceneLayer3D;
+    if (!['3DObject', 'IntegratedMesh'].includes(layer.layerType))
+      throw new Error('Conversion accepts I3S 3DObject or IntegratedMesh layers.');
+    // Reuse the inspected root; all further metadata requests are still charged.
+    const rootFetcher = transport.fetcher;
+    const cachedFetcher: typeof fetch = (url, options) => {
+      const requestUrl = new URL(url instanceof Request ? url.url : String(url));
+      const root = new URL(transport.rootUrl);
+      return requestUrl.origin === root.origin && requestUrl.pathname === root.pathname
+        ? Promise.resolve(new Response(JSON.stringify(layer)))
+        : rootFetcher(url, options);
+    };
+    runtime = createRuntime({...transport, fetcher: cachedFetcher});
+    await runtime.tilesetInitializationPromise;
+    await createI3SMeshTilesetConversionSource(runtime).inspect(signal);
+    const stack = [runtime.root!];
+    const identifiers = new Set<string>();
+    const resources: I3SMeshConversionResourceDescriptor[] = [];
+    while (stack.length) {
+      signal.throwIfAborted();
+      const tile = stack.pop()!;
+      if (
+        !['string', 'number'].includes(typeof tile.header.id) ||
+        String(tile.header.id).length === 0
+      )
+        throw new Error('I3S nodes require a declared identity.');
+      const identifier = String(tile.header.id);
+      if (identifiers.has(identifier))
+        throw new Error('Repeated I3S node identity is unsupported.');
+      identifiers.add(identifier);
+      if (
+        identifiers.size + stack.length + (tile.header.children?.length ?? 0) >
+        (options.maxInputResources ?? SELECTED_MESH_LIMITS.maxInputResources)
+      )
+        throw new Error('I3S inspection exceeds the 1,000 node limit.');
+      await runtime.source.loadTileChildrenForTraversal!(tile, signal);
+      if (!tile.children.length && tile.contentUrl)
+        resources.push({
+          resourceId: identifier,
+          uri: tile.contentUrl,
+          header: structuredClone(tile.header)
+        });
+      for (const child of [...tile.children].reverse()) stack.push(child);
+    }
+    signal.throwIfAborted();
+    if (!resources.length) throw new Error('No supported leaf mesh nodes are declared.');
+    return {
+      kind: 'i3s',
+      rootUrl: transport.rootUrl,
+      layer,
+      resources,
+      metadataBytes: 0
+    };
+  } finally {
+    runtime?.destroy();
+  }
+}
+
+/** Converts explicitly selected I3S leaf meshes into a bounded flat collection in either format. */
+export async function createSelectedI3SMeshConversionSource(
+  inspection: I3SMeshConversionInspection,
+  options: I3SMeshSelectionOptions & {
+    /** Explicit distinct inspected leaf-node identities. */
+    readonly resourceIds: readonly string[];
+    /** Explicit attribute mapping for feature-bearing meshes. */
+    readonly features?: I3SMeshSourceFeatureOptions;
+  }
+) {
+  const {resourceIds, signal, features} = options;
+  validateSelectionOptions(options);
+  signal.throwIfAborted();
+  if (inspection.rootUrl !== options.rootUrl)
+    throw new TileConversionError(
+      'INVALID_I3S_SELECTION',
+      'Selection transport must match the inspected layer'
+    );
+  if (
+    !resourceIds.length ||
+    resourceIds.length > SELECTED_MESH_LIMITS.maxSelectedResources ||
+    new Set(resourceIds).size !== resourceIds.length ||
+    resourceIds.some(
+      identifier => !inspection.resources.some(resource => resource.resourceId === identifier)
+    )
+  )
+    throw new Error('Select between 1 and 64 distinct leaf mesh nodes.');
+  const selected = inspection.resources.filter(resource =>
+    resourceIds.includes(resource.resourceId)
+  );
+  if (
+    selected.some(
+      resource =>
+        resource.header.children?.length ||
+        !resource.header.contentUrl ||
+        resource.uri !== resource.header.contentUrl
+    )
+  )
+    throw new Error('Only inspected leaf mesh headers can be converted.');
+  const transport = options;
+  let decodedBytes = 0;
+  let meshCount = 0;
+  {
+    const qualification = createRuntime(transport, inspection.layer, selected[0].header);
+    let spatialContext: ReturnType<typeof createI3SConversionSpatialContext>;
+    try {
+      await qualification.tilesetInitializationPromise;
+      const metadata = await createI3SMeshTilesetConversionSource(qualification).inspect(signal);
+      spatialContext = createI3SConversionSpatialContext(metadata.spatialReference!, {
+        targetCrs: 'EPSG:4978'
+      });
+    } finally {
+      qualification.destroy();
+    }
+    const source = {
+      /** Reuses only immutable inspected declarations. */
+      inspect: async () => inspection,
+      /** Releases each dedicated node runtime before moving on or closing early. */
+      async *read() {
+        for (const descriptor of selected) {
+          const runtime = createRuntime(transport, inspection.layer, descriptor.header);
+          try {
+            await runtime.tilesetInitializationPromise;
+            const meshSource = createI3SMeshTilesetConversionSource(runtime, {
+              unloadContent: true,
+              features,
+              readExternalResource: async uri =>
+                new Uint8Array(
+                  await (await transport.fetcher(runtime.source.getTileUrl(uri))).arrayBuffer()
+                )
+            });
+            const metadata = await meshSource.inspect(signal);
+            for await (const resource of meshSource.read(metadata, signal)) {
+              decodedBytes += measureMeshBytes(resource);
+              if (
+                ++meshCount > SELECTED_MESH_LIMITS.maxMeshResources ||
+                decodedBytes > (options.maxInputBytes ?? SELECTED_MESH_LIMITS.maxInputBytes)
+              )
+                throw new TileConversionError(
+                  'INPUT_RESOURCE_TOO_LARGE',
+                  'Selected I3S decoded resources exceed the input/mesh budget'
+                );
+              yield {...resource, id: descriptor.resourceId};
+            }
+          } finally {
+            runtime.destroy();
+          }
+        }
+      }
+    };
+    return {source, spatialContext};
+  }
+}
+
+/** Keeps public selected-source limits within the same bounded profile as platform adapters. */
+function validateSelectionOptions(options: I3SMeshSelectionOptions): void {
+  for (const [value, maximum] of [
+    [
+      options.maxInputBytes ?? SELECTED_MESH_LIMITS.maxInputBytes,
+      SELECTED_MESH_LIMITS.maxInputBytes
+    ],
+    [
+      options.maxInputResources ?? SELECTED_MESH_LIMITS.maxInputResources,
+      SELECTED_MESH_LIMITS.maxInputResources
+    ]
+  ])
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
+      throw new TileConversionError(
+        'INVALID_I3S_SELECTION_LIMIT',
+        'I3S selection limits must be positive safe integers within the bounded profile'
+      );
+}

package/src/v5/index.ts

@@ -129,3 +129,29 @@ export type {
   I3SMeshTilesetSourceOptions,
   I3SMeshSourceFeatureOptions
 } from '@loaders.gl/tile-converter/v5/adapters';
+
+export {convertPointCloudToTileset} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  ConvertPointCloudToTilesetOptions,
+  ConvertedPointCloudTileset
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {
+  encodePotreeArchive,
+  openPointCloudFile,
+  extractMeshVertices
+} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  EncodePotreeArchiveOptions,
+  OpenPointCloudFileOptions,
+  OpenedPointCloudFile,
+  ExtractMeshVerticesOptions
+} from '@loaders.gl/tile-converter/v5/adapters';
+
+export {createMeshSourceFeatureOptions} from '@loaders.gl/tile-converter/v5/adapters';
+export type {MeshSourceSchemaOptions} from '@loaders.gl/tile-converter/v5/adapters';
+export {convertPointCloudToPotree} from '@loaders.gl/tile-converter/v5/adapters';
+export type {
+  ConvertPointCloudToPotreeOptions,
+  ConvertedPointCloudPotree
+} from '@loaders.gl/tile-converter/v5/adapters';

package/src/v5/mesh-conversion.ts

@@ -21,6 +21,15 @@ import {encodeDracoMeshTile} from './mesh-draco.js';
 export interface MeshConversionInput {
   /** Caller-owned resource identifier, forwarded to the output sink. */
   readonly id: string;
+  /** Inspected content placement, used by the hierarchy sink independently of primitive IDs. */
+  readonly contentResourceId?: string;
+  /** Ordered primitive within a content; last marks complete extraction for hierarchy authoring. */
+  readonly contentPrimitive?: {
+    /** Zero-based primitive placement index in scene traversal order. */
+    readonly index: number;
+    /** Whether this is the final primitive placement in the content. */
+    readonly last: boolean;
+  };
   /** Triangle geometry with absolute packed Float32 or Float64 source positions. */
   readonly mesh: MeshGeometry;
   /** Original I3S vector basis; overrides the codec default when supplied by a source. */
@@ -37,6 +46,15 @@ export interface MeshConversionInput {
 export interface EncodedMeshConversionResource {
   /** Caller-owned resource identifier. */
   readonly id: string;
+  /** Inspected content placement, retained by the codec for hierarchy authoring. */
+  readonly contentResourceId?: string;
+  /** Ordered primitive within a content; last marks complete extraction for hierarchy authoring. */
+  readonly contentPrimitive?: {
+    /** Zero-based primitive placement index in scene traversal order. */
+    readonly index: number;
+    /** Whether this is the final primitive placement in the content. */
+    readonly last: boolean;
+  };
   /** Self-contained GLB with local positions and transformed normals. */
   readonly glb: ArrayBuffer;
   /** Target-frame translation to add to the encoded positions. */
@@ -205,6 +223,8 @@ export function createMeshConversionCodec<TInspection = unknown>(
       }
       yield {
         id: resource.id,
+        contentResourceId: resource.contentResourceId,
+        contentPrimitive: resource.contentPrimitive,
         glb: encoded.glb,
         origin,
         boundingBox: [minimum, maximum],