@loaders.gl/arcgis 5.0.0-alpha.8

package/src/arcgis/arcgis-image-tile-source-loader.ts

@@ -0,0 +1,192 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {ArcGISAuthentication} from '../authentication';
+import {ARCGIS_IMAGE_TILE_SOURCE_LOADER_METADATA} from '../arcgis-source-types';
+import type {ArcGISImageTileSourceLoaderOptions} from '../arcgis-source-types';
+
+import type {ImageType} from '@loaders.gl/images';
+import {ImageLoader} from '@loaders.gl/images';
+import type {
+  CoreAPI,
+  GetTileDataParameters,
+  GetTileParameters,
+  SourceLoader,
+  TileSource,
+  TileSourceMetadata
+} from '@loaders.gl/loader-utils';
+import {DataSource} from '@loaders.gl/loader-utils';
+import type {LERCData} from '@loaders.gl/lerc';
+import {LERCLoader} from '@loaders.gl/lerc';
+
+/** A tile source that renders ArcGIS ImageServer exports as deck.gl tiles. */
+export class ArcGISImageTileSource
+  extends DataSource<string, ArcGISImageTileSourceLoaderOptions>
+  implements TileSource
+{
+  /** MIME type represented by the tile response. */
+  readonly mimeType: string;
+
+  /** Cached ImageServer metadata. */
+  private _metadata: any | null = null;
+  /** In-flight metadata request shared by concurrent callers. */
+  private _metadataPromise: Promise<any> | null = null;
+  /** Parameters applied to subsequent export requests. */
+  private _runtimeParameters: Record<string, string | number | boolean> = {};
+
+  /** Creates an ArcGIS ImageServer tile source. */
+  constructor(url: string, options: ArcGISImageTileSourceLoaderOptions = {}, coreApi?: CoreAPI) {
+    super(
+      url.replace(/\/$/, ''),
+      options,
+      ARCGIS_IMAGE_TILE_SOURCE_LOADER_METADATA.defaultOptions,
+      coreApi
+    );
+    this.mimeType = this._getResponseFormat() === 'lerc' ? 'application/octet-stream' : 'image/png';
+    this.getTileData = this.getTileData.bind(this);
+  }
+
+  /** Returns normalized ImageServer metadata. */
+  async getMetadata(): Promise<TileSourceMetadata> {
+    const metadata = await this._getMetadata();
+    const extent = metadata.fullExtent || metadata.extent;
+    const spatialReference = metadata.spatialReference || extent?.spatialReference;
+    return {
+      name: metadata.name || metadata.serviceDescription || '',
+      title: metadata.name || metadata.serviceDescription || '',
+      abstract: metadata.description || metadata.serviceDescription || '',
+      attributions: metadata.copyrightText ? [metadata.copyrightText] : undefined,
+      boundingBox: extent
+        ? [
+            [extent.xmin, extent.ymin],
+            [extent.xmax, extent.ymax]
+          ]
+        : undefined,
+      layer: {
+        name: metadata.name || '',
+        srs: spatialReference?.wkid ? [`EPSG:${spatialReference.wkid}`] : [],
+        layers: []
+      }
+    };
+  }
+
+  /** Fetches one ImageServer export tile. */
+  async getTile(
+    parameters: GetTileParameters,
+    signal?: AbortSignal
+  ): Promise<ImageType | LERCData | null> {
+    const response = await this.fetch(this.getTileURL(parameters), signal ? {signal} : undefined);
+    if (!response.ok) {
+      throw new Error(
+        `ArcGIS ImageServer tile request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    const loader = this._getResponseFormat() === 'lerc' ? LERCLoader : ImageLoader;
+    return (await this.coreApi.parse(
+      await response.arrayBuffer(),
+      loader,
+      this.loadOptions
+    )) as ImageType;
+  }
+
+  /** Fetches a tile using the deck.gl-compatible request shape. */
+  async getTileData(parameters: GetTileDataParameters): Promise<ImageType | LERCData | null> {
+    return this.getTile(parameters.index, parameters.signal);
+  }
+
+  /** Updates parameters applied to subsequent ImageServer export requests. */
+  updateParameters(parameters: Record<string, string | number | boolean>): void {
+    this._runtimeParameters = {...this._runtimeParameters, ...parameters};
+  }
+
+  /** Builds an ImageServer exportImage URL for one web-mercator tile. */
+  getTileURL(parameters: GetTileParameters, tileSize?: number): string {
+    const options = this.options['arcgis-image-server-tiles'] || {};
+    const resolvedTileSize = tileSize || options.tileSize || 256;
+    const [west, south, east, north] = getWebMercatorTileBounds(parameters);
+    const url = new URL(this.getServiceURL(parameters));
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/exportImage`;
+    const requestParameters = {
+      f: 'image',
+      bbox: `${west},${south},${east},${north}`,
+      bboxSR: 3857,
+      imageSR: 3857,
+      size: `${resolvedTileSize},${resolvedTileSize}`,
+      format: this._getResponseFormat(),
+      transparent: true,
+      ...options.parameters,
+      ...this._runtimeParameters
+    };
+    for (const [key, value] of Object.entries(requestParameters)) {
+      url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+
+  /** Fetches the ImageServer metadata document. */
+  private async _loadMetadata(): Promise<any> {
+    const url = new URL(this.url);
+    url.searchParams.set('f', 'pjson');
+    const response = await this.fetch(url.toString());
+    if (!response.ok) {
+      throw new Error(`ArcGIS ImageServer metadata request failed: ${response.status}`);
+    }
+    return response.json();
+  }
+
+  /** Returns cached metadata and shares a single request among concurrent callers. */
+  private async _getMetadata(): Promise<any> {
+    if (this._metadata) return this._metadata;
+    if (!this._metadataPromise) {
+      this._metadataPromise = this._loadMetadata();
+    }
+    try {
+      const metadata = await this._metadataPromise;
+      this._metadata = metadata;
+      return metadata;
+    } finally {
+      this._metadataPromise = null;
+    }
+  }
+
+  /** Selects a service endpoint for a tile using a stable URL-pool mapping. */
+  private getServiceURL(parameters: GetTileParameters): string {
+    const urls = this.options['arcgis-image-server-tiles']?.urls;
+    return urls?.length ? urls[(parameters.x + parameters.y) % urls.length] : this.url;
+  }
+
+  /** Returns the response format after applying configured and runtime overrides. */
+  private _getResponseFormat(): 'png32' | 'lerc' {
+    const options = this.options['arcgis-image-server-tiles'] || {};
+    const format = this._runtimeParameters.format || options.parameters?.format || options.format;
+    return format === 'lerc' ? 'lerc' : 'png32';
+  }
+}
+
+/** Runtime service loader for synchronous construction. */
+export const ArcGISImageTileSourceLoaderWithParser = {
+  ...ARCGIS_IMAGE_TILE_SOURCE_LOADER_METADATA,
+  dataType: null as unknown as ArcGISImageTileSource,
+  batchType: null as never,
+  preload: undefined,
+  /** Supplies ArcGIS credentials after loading the selected implementation. */
+  getAuthentications: () => [ArcGISAuthentication],
+  createDataSource: (
+    url: string,
+    options: ArcGISImageTileSourceLoaderOptions = {},
+    coreApi?: CoreAPI
+  ) => new ArcGISImageTileSource(url, options, coreApi)
+} as const satisfies SourceLoader<ArcGISImageTileSource>;
+
+/** Calculates the Web Mercator extent represented by an XYZ tile. */
+function getWebMercatorTileBounds(parameters: GetTileParameters): [number, number, number, number] {
+  const worldSize = 20037508.342789244;
+  const tileCount = 2 ** parameters.z;
+  const tileSize = (worldSize * 2) / tileCount;
+  const west = -worldSize + parameters.x * tileSize;
+  const east = west + tileSize;
+  const north = worldSize - parameters.y * tileSize;
+  const south = north - tileSize;
+  return [west, south, east, north];
+}

package/src/arcgis/arcgis-map-tile-source-loader-types.ts

@@ -0,0 +1,34 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {ARCGIS_MAP_TILE_SOURCE_LOADER_METADATA} from '../arcgis-source-types';
+import type {CoreAPI, SourceLoader} from '@loaders.gl/loader-utils';
+import type {ArcGISMapTileSource} from './arcgis-map-tile-source-loader';
+import type {ArcGISMapTileSourceLoaderOptions} from '../arcgis-source-types';
+
+/** Loads the ArcGISMapTileSourceLoader implementation on first asynchronous use. */
+async function preloadArcGISMapTileSourceLoader(): Promise<SourceLoader<ArcGISMapTileSource>> {
+  const {ArcGISMapTileSourceLoaderWithParser} = await import(
+    '@loaders.gl/arcgis/arcgis-map-tile-source-loader'
+  );
+  return ArcGISMapTileSourceLoaderWithParser;
+}
+
+/** Lightweight service descriptor; use load() or the synchronous /bundled entrypoint. */
+export const ArcGISMapTileSourceLoader = {
+  ...ARCGIS_MAP_TILE_SOURCE_LOADER_METADATA,
+  dataType: null as unknown as ArcGISMapTileSource,
+  batchType: null as never,
+  preload: preloadArcGISMapTileSourceLoader,
+  /** Requires the runtime loader when constructing a source synchronously. */
+  createDataSource(
+    _url: string,
+    _options: ArcGISMapTileSourceLoaderOptions,
+    _coreApi?: CoreAPI
+  ): ArcGISMapTileSource {
+    throw new Error(
+      'ArcGISMapTileSourceLoader requires async load() or an @loaders.gl/arcgis/bundled import'
+    );
+  }
+} as const satisfies SourceLoader<ArcGISMapTileSource>;

package/src/arcgis/arcgis-map-tile-source-loader.ts

@@ -0,0 +1,248 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {ArcGISAuthentication} from '../authentication';
+import {ARCGIS_MAP_TILE_SOURCE_LOADER_METADATA} from '../arcgis-source-types';
+import type {
+  ArcGISMapTileSourceLoaderOptions,
+  ArcGISMapServerMetadata,
+  ArcGISMapTileParameters
+} from '../arcgis-source-types';
+
+import type {ImageType} from '@loaders.gl/images';
+import {ImageLoader} from '@loaders.gl/images';
+import type {
+  CoreAPI,
+  GetTileDataParameters,
+  GetTileParameters,
+  SourceLoader,
+  TileSource,
+  TileSourceMetadata
+} from '@loaders.gl/loader-utils';
+import {DataSource} from '@loaders.gl/loader-utils';
+
+/** ArcGIS MapServer source for cached `/tile/{z}/{y}/{x}` image tiles. */
+export class ArcGISMapTileSource
+  extends DataSource<string, ArcGISMapTileSourceLoaderOptions>
+  implements TileSource
+{
+  /** MIME type rendered by the generic deck.gl tile adapter. */
+  readonly mimeType = 'image/png';
+
+  /** Cached service metadata. */
+  private _metadata: ArcGISMapServerMetadata | null = null;
+  /** In-flight metadata request shared by concurrent callers. */
+  private _metadataPromise: Promise<ArcGISMapServerMetadata> | null = null;
+  /** Parameters applied to subsequent dynamic exports. */
+  private _runtimeParameters: ArcGISMapTileParameters = {};
+
+  /** Creates an ArcGIS MapServer tile source. */
+  constructor(url: string, options: ArcGISMapTileSourceLoaderOptions = {}, coreApi?: CoreAPI) {
+    super(
+      url.replace(/\/$/, ''),
+      options,
+      ARCGIS_MAP_TILE_SOURCE_LOADER_METADATA.defaultOptions,
+      coreApi
+    );
+    this.getTileData = this.getTileData.bind(this);
+  }
+
+  /** Loads and normalizes ArcGIS service metadata. */
+  async getMetadata(): Promise<TileSourceMetadata> {
+    const metadata = await this._getMetadata();
+    const extent = metadata.fullExtent;
+    const spatialReference = metadata.spatialReference || extent?.spatialReference;
+    const spatialReferenceWkid = (spatialReference as {wkid?: number} | undefined)?.wkid;
+    return {
+      name: metadata.name || '',
+      title: metadata.name || '',
+      abstract: metadata.description || metadata.serviceDescription || '',
+      attributions: metadata.copyrightText ? [metadata.copyrightText] : undefined,
+      minZoom: 0,
+      maxZoom: metadata.tileInfo?.lods?.length
+        ? Math.max(...metadata.tileInfo.lods.map(lod => lod.level))
+        : undefined,
+      boundingBox: extent
+        ? [
+            [extent.xmin, extent.ymin],
+            [extent.xmax, extent.ymax]
+          ]
+        : undefined,
+      layer: {
+        name: metadata.name || '',
+        srs: spatialReferenceWkid ? [`EPSG:${spatialReferenceWkid}`] : [],
+        layers: []
+      },
+      tileGrid: metadata.tileInfo
+        ? {
+            crs: (metadata.tileInfo.spatialReference as {wkid?: number} | undefined)?.wkid
+              ? `EPSG:${(metadata.tileInfo.spatialReference as {wkid: number}).wkid}`
+              : undefined,
+            tileSize:
+              metadata.tileInfo.rows && metadata.tileInfo.cols
+                ? [metadata.tileInfo.cols, metadata.tileInfo.rows]
+                : undefined,
+            origin: metadata.tileInfo.origin
+              ? [metadata.tileInfo.origin.x, metadata.tileInfo.origin.y]
+              : undefined,
+            matrixIds: metadata.tileInfo.lods?.map(lod => String(lod.level))
+          }
+        : undefined
+    };
+  }
+
+  /** Fetches and decodes one cached ArcGIS tile. */
+  async getTile(parameters: GetTileParameters, signal?: AbortSignal): Promise<ImageType | null> {
+    const options = this.options['arcgis-map-server'] || {};
+    const mode = options.mode || 'auto';
+    const metadata = mode === 'auto' ? await this._getMetadata() : null;
+    const useCachedTiles = mode === 'cached' || (mode === 'auto' && isCompatibleCache(metadata));
+    const tileURL = useCachedTiles
+      ? this.getTileURL(parameters)
+      : this.getExportTileURL(parameters, options.tileSize || 256);
+    const response = await this.fetch(tileURL, signal ? {signal} : undefined);
+    if (!response.ok) {
+      throw new Error(
+        `ArcGIS MapServer tile request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    return (await this.coreApi.parse(
+      await response.arrayBuffer(),
+      ImageLoader,
+      this.loadOptions
+    )) as ImageType;
+  }
+
+  /** Fetches a tile using the deck.gl-compatible request shape. */
+  async getTileData(parameters: GetTileDataParameters): Promise<ImageType | null> {
+    return this.getTile(parameters.index, parameters.signal);
+  }
+
+  /** Builds the standard ArcGIS cached tile URL. */
+  getTileURL(parameters: GetTileParameters): string {
+    const template = this.options['arcgis-map-server']?.urlTemplate;
+    if (template) {
+      const templateURL = new URL(
+        template
+          .replaceAll('{z}', String(parameters.z))
+          .replaceAll('{y}', String(parameters.y))
+          .replaceAll('{x}', String(parameters.x))
+      );
+      return templateURL.toString();
+    }
+    const url = new URL(this.getServiceURL(parameters));
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/tile/${parameters.z}/${parameters.y}/${parameters.x}`;
+    return url.toString();
+  }
+
+  /** Updates parameters applied to subsequent dynamic MapServer export requests. */
+  updateParameters(parameters: ArcGISMapTileParameters): void {
+    this._runtimeParameters = {...this._runtimeParameters, ...parameters};
+  }
+
+  /** Builds a dynamic MapServer `export` request for one web-mercator tile. */
+  getExportTileURL(parameters: GetTileParameters, tileSize?: number): string {
+    const options = this.options['arcgis-map-server'] || {};
+    const resolvedTileSize = tileSize || options.tileSize || 256;
+    const [west, south, east, north] = getWebMercatorTileBounds(parameters);
+    const url = new URL(this.getServiceURL(parameters));
+    url.pathname = `${url.pathname.replace(/\/$/, '')}/export`;
+    const searchParameters: ArcGISMapTileParameters = {
+      f: 'image',
+      bbox: `${west},${south},${east},${north}`,
+      bboxSR: 3857,
+      imageSR: 3857,
+      size: `${resolvedTileSize},${resolvedTileSize}`,
+      format: 'png32',
+      transparent: true,
+      ...options.exportParameters,
+      ...this._runtimeParameters
+    };
+    for (const [key, value] of Object.entries(searchParameters)) {
+      url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+
+  /** Fetches the MapServer metadata document and applies configured parameters. */
+  private async _loadMetadata(): Promise<ArcGISMapServerMetadata> {
+    const configuredMetadata = this.options['arcgis-map-server']?.metadata;
+    if (configuredMetadata) return configuredMetadata;
+    const url = new URL(this.url);
+    url.searchParams.set('f', 'pjson');
+    for (const [key, value] of Object.entries(
+      this.options['arcgis-map-server']?.parameters || {}
+    )) {
+      url.searchParams.set(key, value);
+    }
+    const response = await this.fetch(url.toString());
+    if (!response.ok) {
+      throw new Error(
+        `ArcGIS MapServer metadata request failed: ${response.status} ${response.statusText}`
+      );
+    }
+    return response.json();
+  }
+
+  /** Returns cached metadata and shares a single request among concurrent callers. */
+  private async _getMetadata(): Promise<ArcGISMapServerMetadata> {
+    if (this._metadata) return this._metadata;
+    if (!this._metadataPromise) {
+      this._metadataPromise = this._loadMetadata();
+    }
+    try {
+      const metadata = await this._metadataPromise;
+      this._metadata = metadata;
+      return metadata;
+    } finally {
+      this._metadataPromise = null;
+    }
+  }
+
+  /** Selects a service endpoint for a tile using a stable URL-pool mapping. */
+  private getServiceURL(parameters: GetTileParameters): string {
+    const urls = this.options['arcgis-map-server']?.urls;
+    return urls?.length ? urls[(parameters.x + parameters.y) % urls.length] : this.url;
+  }
+}
+
+function isCompatibleCache(metadata: ArcGISMapServerMetadata | null): boolean {
+  const tileInfo = metadata?.tileInfo;
+  if (!tileInfo || tileInfo.rows !== 256 || tileInfo.cols !== 256) return false;
+  const spatialReference = tileInfo.spatialReference || metadata?.spatialReference;
+  const wkid = (spatialReference as {wkid?: number; latestWkid?: number} | undefined)?.wkid;
+  if (wkid !== 3857 && wkid !== 102100 && wkid !== 102113) return false;
+  const origin = tileInfo.origin;
+  return (
+    !origin ||
+    (Math.abs(origin.x + 20037508.342789244) < 1 && Math.abs(origin.y - 20037508.342789244) < 1)
+  );
+}
+
+/** Calculates the Web Mercator extent represented by an XYZ tile. */
+function getWebMercatorTileBounds(parameters: GetTileParameters): [number, number, number, number] {
+  const worldSize = 20037508.342789244;
+  const tileCount = 2 ** parameters.z;
+  const tileSize = (worldSize * 2) / tileCount;
+  const west = -worldSize + parameters.x * tileSize;
+  const east = west + tileSize;
+  const north = worldSize - parameters.y * tileSize;
+  const south = north - tileSize;
+  return [west, south, east, north];
+}
+
+/** Runtime service loader for synchronous construction. */
+export const ArcGISMapTileSourceLoaderWithParser = {
+  ...ARCGIS_MAP_TILE_SOURCE_LOADER_METADATA,
+  dataType: null as unknown as ArcGISMapTileSource,
+  batchType: null as never,
+  preload: undefined,
+  /** Supplies ArcGIS credentials after loading the selected implementation. */
+  getAuthentications: () => [ArcGISAuthentication],
+  createDataSource: (
+    url: string,
+    options: ArcGISMapTileSourceLoaderOptions = {},
+    coreApi?: CoreAPI
+  ) => new ArcGISMapTileSource(url, options, coreApi)
+} as const satisfies SourceLoader<ArcGISMapTileSource>;

package/src/arcgis/arcgis-scene-aggregation.ts

@@ -0,0 +1,90 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Aggregation operation supported by the SceneServer client helper. */
+export type ArcGISSceneAggregationOperation = 'count' | 'sum' | 'min' | 'max' | 'average';
+
+/** A single aggregation specification. */
+export type ArcGISSceneAggregationSpec = {
+  /** Output field name. */
+  name: string;
+  /** Input property used by numeric operations. */
+  field?: string;
+  /** Operation to apply. */
+  operation: ArcGISSceneAggregationOperation;
+};
+
+/** Options for deterministic client-side feature aggregation. */
+export type ArcGISSceneAggregationOptions = {
+  /** Features represented as ArcGIS feature objects or plain attribute records. */
+  features: unknown[];
+  /** Optional property used to create groups. */
+  groupBy?: string;
+  /** Aggregations to compute for each group. */
+  aggregations: ArcGISSceneAggregationSpec[];
+};
+
+/** Result of one group in a client-side aggregation. */
+export type ArcGISSceneAggregationGroup = {
+  /** Group key, or `undefined` when no grouping was requested. */
+  group: unknown;
+  /** Aggregated values keyed by specification name. */
+  values: Record<string, number>;
+};
+
+/**
+ * Aggregates SceneServer features without evaluating renderer or Arcade expressions.
+ * Missing and non-numeric values are ignored by numeric operations; `count` counts
+ * records regardless of field presence.
+ */
+export function aggregateArcGISSceneFeatures(
+  options: ArcGISSceneAggregationOptions
+): ArcGISSceneAggregationGroup[] {
+  const groups = new Map<unknown, unknown[]>();
+  for (const feature of options.features) {
+    const attributes = getFeatureAttributes(feature);
+    const key = options.groupBy ? attributes[options.groupBy] : undefined;
+    const group = groups.get(key);
+    if (group) group.push(feature);
+    else groups.set(key, [feature]);
+  }
+
+  return [...groups.entries()].map(([group, features]) => ({
+    group,
+    values: Object.fromEntries(
+      options.aggregations.map(spec => [spec.name, aggregateValues(features, spec)])
+    )
+  }));
+}
+
+function aggregateValues(features: unknown[], specification: ArcGISSceneAggregationSpec): number {
+  if (specification.operation === 'count') return features.length;
+  const values = features
+    .map(feature => getFeatureAttributes(feature)[specification.field || ''])
+    .filter(value => value !== null && value !== undefined && value !== '')
+    .map(value => (typeof value === 'number' ? value : Number(value)))
+    .filter(Number.isFinite);
+  if (!values.length) return 0;
+  switch (specification.operation) {
+    case 'sum':
+      return values.reduce((sum, value) => sum + value, 0);
+    case 'min':
+      return Math.min(...values);
+    case 'max':
+      return Math.max(...values);
+    case 'average':
+      return values.reduce((sum, value) => sum + value, 0) / values.length;
+    default:
+      return 0;
+  }
+}
+
+function getFeatureAttributes(feature: unknown): Record<string, unknown> {
+  if (!feature || typeof feature !== 'object') return {};
+  const candidate = feature as {attributes?: unknown};
+  if (candidate.attributes && typeof candidate.attributes === 'object') {
+    return candidate.attributes as Record<string, unknown>;
+  }
+  return feature as Record<string, unknown>;
+}

package/src/arcgis/arcgis-scene-server-source-loader-types.ts

@@ -0,0 +1,36 @@
+// loaders.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {ARCGIS_SCENE_SERVER_SOURCE_LOADER_METADATA} from '../arcgis-source-types';
+import type {CoreAPI, SourceLoader} from '@loaders.gl/loader-utils';
+import type {ArcGISSceneServerSource} from './arcgis-scene-server-source-loader';
+import type {ArcGISSceneServerSourceOptions} from '../arcgis-source-types';
+
+/** Loads the ArcGISSceneServerSourceLoader implementation on first asynchronous use. */
+async function preloadArcGISSceneServerSourceLoader(): Promise<
+  SourceLoader<ArcGISSceneServerSource>
+> {
+  const {ArcGISSceneServerSourceLoaderWithParser} = await import(
+    '@loaders.gl/arcgis/arcgis-scene-server-source-loader'
+  );
+  return ArcGISSceneServerSourceLoaderWithParser;
+}
+
+/** Lightweight service descriptor; use load() or the synchronous /bundled entrypoint. */
+export const ArcGISSceneServerSourceLoader = {
+  ...ARCGIS_SCENE_SERVER_SOURCE_LOADER_METADATA,
+  dataType: null as unknown as ArcGISSceneServerSource,
+  batchType: null as never,
+  preload: preloadArcGISSceneServerSourceLoader,
+  /** Requires the runtime loader when constructing a source synchronously. */
+  createDataSource(
+    _url: string,
+    _options: ArcGISSceneServerSourceOptions,
+    _coreApi?: CoreAPI
+  ): ArcGISSceneServerSource {
+    throw new Error(
+      'ArcGISSceneServerSourceLoader requires async load() or an @loaders.gl/arcgis/bundled import'
+    );
+  }
+} as const satisfies SourceLoader<ArcGISSceneServerSource>;