maplibre-gl-layers 0.19.0 → 1.1.0

package/dist/index.d.ts

@@ -1,15 +1,1361 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.19.0
+ * version: 1.1.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
+ * git.commit.hash: 6308f45aa959024297cb716990f16213b89b6bd0
  */
 
-export * from './types';
-export * from './default';
-export * from './utils/image';
-export { initializeRuntimeHost, releaseRuntimeHost, detectMultiThreadedModuleAvailability, type MultiThreadedModuleAvailability, } from './host/runtime';
-export * from './SpriteLayer';
+import { CustomLayerInterface } from 'maplibre-gl';
+
+/**
+ * Applies auto-rotation to all images within a sprite when movement exceeds the configured threshold.
+ * @template T Arbitrary sprite tag type.
+ * @param {InternalSpriteCurrentState<T>} sprite - Sprite undergoing potential rotation update.
+ * @param {SpriteLocation} nextLocation - Destination location used to derive bearing and distance.
+ * @returns {boolean} `true` when auto-rotation was applied, `false` otherwise.
+ */
+export declare const applyAutoRotation: <T>(sprite: InternalSpriteCurrentState<T>, nextLocation: SpriteLocation, forceAutoRotation: boolean) => boolean;
+
+/**
+ * Better text filtering options than default options.
+ */
+export declare const BETTER_TEXTURE_FILTERING_OPTIONS: SpriteTextureFilteringOptions;
+
+/**
+ * Creates internal sprite image state from initialization data and layer bookkeeping fields.
+ * @param {SpriteImageDefinitionInit} imageInit - Caller-provided image definition.
+ * @param {number} subLayer - Sub-layer index the image belongs to.
+ * @param {number} order - Ordering slot within the sub-layer.
+ * @param {SpriteOriginReference} originReference - Encode/Decode origin reference.
+ * @param {boolean} invalidated - Initially invalidate state.
+ * @returns {InternalSpriteImageState} Normalized internal state ready for rendering.
+ */
+export declare const createImageStateFromInit: (imageInit: SpriteImageDefinitionInit, subLayer: number, order: number, originReference: SpriteOriginReference, invalidated: boolean, spriteAutoRotationDeg?: number) => InternalSpriteImageState;
+
+/**
+ * Factory that creates the MapLibre layer interface for the sprite layer.
+ * Implements the CustomLayerInterface lifecycle (init -> render -> dispose), packing thousands
+ * of sprites into GPU buffers for efficient rendering. Supports optional scaling controls for
+ * billboard and surface modes.
+ *
+ * @template T Arbitrary tag type for per-sprite metadata.
+ * @param {SpriteLayerOptions} [options] Initial layer options such as ID or scaling settings.
+ * @returns {SpriteLayerInterface<T>} Interface for sprite add/update/remove operations and MapLibre hooks.
+ */
+export declare const createSpriteLayer: <T = any>(options?: SpriteLayerOptions) => SpriteLayerInterface<T>;
+
+/**
+ * Defaulted text filtering options.
+ */
+export declare const DEFAULT_TEXTURE_FILTERING_OPTIONS: SpriteTextureFilteringOptions;
+
+/**
+ * Detects SIMD and multi-threading module availability.
+ * @returns MultiThreadedModuleAvailability.
+ */
+export declare const detectMultiThreadedModuleAvailability: () => MultiThreadedModuleAvailability;
+
+/**
+ * Easing function type.
+ */
+declare type EasingFunction = (progress: number) => number;
+
+/**
+ * The handle value that using the instance.
+ */
+declare type IdHandle = number;
+
+/**
+ * Initialize maplibre-gl-layers runtime host.
+ * @param variantOrOptions Options.
+ * @returns Initialized calculation variant.
+ */
+export declare const initializeRuntimeHost: (options?: SpriteLayerHostOptions) => Promise<SpriteLayerCalculationVariant>;
+
+/**
+ * Current sprite mutable state view tracked internally by the layer.
+ */
+declare interface InternalSpriteCurrentState<TTag> extends SpriteCurrentState<TTag> {
+    spriteId: string;
+    handle: IdHandle;
+    isEnabled: boolean;
+    visibilityDistanceMeters: number | undefined;
+    opacityMultiplier: number;
+    location: MutableSpriteInterpolatedValues<SpriteLocation>;
+    images: Map<number, Map<number, InternalSpriteImageState>>;
+    tag: TTag | null;
+    lastAutoRotationLocation: Readonly<SpriteLocation>;
+    currentAutoRotateDeg: number;
+    autoRotationInvalidated: boolean;
+    interpolationDirty: boolean;
+    cachedMercator: Readonly<SpriteMercatorCoordinate>;
+    cachedMercatorLng: number;
+    cachedMercatorLat: number;
+    cachedMercatorZ: number | undefined;
+}
+
+/**
+ * Base mutable attribute view for an image that composes a sprite.
+ */
+declare interface InternalSpriteImageState extends SpriteImageState {
+    subLayer: number;
+    order: number;
+    imageId: string;
+    imageHandle: number;
+    mode: SpriteMode;
+    scale: number;
+    anchor: Readonly<SpriteAnchor>;
+    border: ResolvedSpriteImageLineAttribute | undefined;
+    borderPixelWidth: number;
+    leaderLine: ResolvedSpriteImageLineAttribute | undefined;
+    leaderLinePixelWidth: number;
+    rotateDeg: number;
+    opacity: number;
+    lodOpacity: number;
+    finalOpacity: MutableSpriteInterpolatedValues<number>;
+    offset: MutableSpriteImageInterpolatedOffset;
+    finalRotateDeg: MutableSpriteInterpolatedValues<number>;
+    autoRotation: boolean;
+    autoRotationMinDistanceMeters: number;
+    originLocation: Readonly<SpriteImageOriginLocation> | undefined;
+    originReferenceKey: SpriteOriginReferenceKey;
+    originRenderTargetIndex: SpriteOriginReferenceIndex;
+    interpolationDirty: boolean;
+    surfaceShaderInputs: Readonly<SurfaceShaderInputs> | undefined;
+    hitTestCorners: [
+    MutableSpriteScreenPoint,
+    MutableSpriteScreenPoint,
+    MutableSpriteScreenPoint,
+    MutableSpriteScreenPoint
+    ] | undefined;
+}
+
+/**
+ * Helper that loads an ImageBitmap from a URL.
+ * @param url Target image URL.
+ * @param options Optional loading options.
+ * @returns Promise resolving to the ImageBitmap.
+ * @remarks This function helps loading SVG with better manner.
+ */
+export declare const loadImageBitmap: (url: string, options?: SpriteImageRegisterOptions) => Promise<ImageBitmap>;
+
+/**
+ * SIMD and multi-threading module availability.
+ */
+export declare interface MultiThreadedModuleAvailability {
+    /** Is available? */
+    readonly available: boolean;
+    /** Not available, reason text */
+    readonly reason?: string;
+}
+
+declare interface MutableSpriteImageInterpolatedOffset extends SpriteImageInterpolatedOffset {
+    offsetMeters: MutableSpriteInterpolatedValues<number>;
+    offsetDeg: MutableSpriteInterpolatedValues<number>;
+}
+
+/**
+ * Mutable counterpart to {@link SpriteInterpolatedValues}, used internally so SpriteLayer
+ * can reuse object references while still exposing readonly snapshots publicly.
+ */
+declare interface MutableSpriteInterpolatedValues<TValue> extends SpriteInterpolatedValues<TValue> {
+    current: TValue;
+    from: TValue | undefined;
+    to: TValue | undefined;
+    invalidated: boolean | undefined;
+    interpolation: MutableSpriteInterpolation<TValue>;
+}
+
+/**
+ * Mutable interpolation states.
+ */
+declare interface MutableSpriteInterpolation<TValue> {
+    state: SpriteInterpolationState<TValue> | null;
+    options: Readonly<SpriteInterpolationOptions> | null;
+    lastCommandValue: TValue;
+    baseValue: TValue | undefined;
+    targetValue: TValue | undefined;
+}
+
+/**
+ * Mutable point reused when computing hit-test corners.
+ */
+declare interface MutableSpriteScreenPoint extends SpriteScreenPoint {
+    x: number;
+    y: number;
+}
+
+/**
+ * Helper that read an ImageBitmap from a blob.
+ * @param blob Target blob.
+ * @param options Optional reading options.
+ * @returns Promise resolving to the ImageBitmap.
+ * @remarks This function helps reading SVG with better manner.
+ */
+export declare const readImageBitmap: (blob: Blob, options?: SpriteImageRegisterOptions) => Promise<ImageBitmap>;
+
+/**
+ * Release maplibre-gl-layers runtime host.
+ * @returns
+ */
+export declare const releaseRuntimeHost: () => void;
+
+/** Line definition resolved for rendering. */
+declare interface ResolvedSpriteImageLineAttribute extends SpriteImageLineAttributeState {
+    readonly rgba: RgbaColor;
+}
+
+declare type RgbaColor = readonly [number, number, number, number];
+
+/**
+ * Anchor within the image.
+ * The sprite's base coordinate maps to this location; range is -1.0 to 1.0 relative to image size.
+ * x: -1.0 at left, 0.0 center, 1.0 right. y: -1.0 bottom, 0.0 center, 1.0 top.
+ * Values outside the range are accepted; clamp externally if needed.
+ */
+export declare interface SpriteAnchor {
+    /** Horizontal offset; -1.0 left edge, 1.0 right edge. */
+    x: number;
+    /** Vertical offset; -1.0 bottom edge, 1.0 top edge. */
+    y: number;
+}
+
+/**
+ * Current runtime state of a sprite.
+ *
+ * @template TTag Tag type.
+ */
+export declare interface SpriteCurrentState<TTag> {
+    /** Sprite identifier. */
+    readonly spriteId: string;
+    /** Indicates whether the sprite is enabled. */
+    readonly isEnabled: boolean;
+    /** Multiplier applied to every image opacity. */
+    readonly opacityMultiplier: number;
+    /**
+     * Pseudo LOD threshold for the sprite. When the camera distance exceeds this value,
+     * the sprite's images become invisible.
+     */
+    readonly visibilityDistanceMeters: number | undefined;
+    /**
+     * Location information including current, source, and destination coordinates.
+     * `from`/`to` are `undefined` when interpolation is inactive.
+     */
+    readonly location: SpriteInterpolatedValues<Readonly<SpriteLocation>>;
+    /** Current image states, grouped by sub-layer and order. */
+    readonly images: ReadonlyMap<number, ReadonlyMap<number, SpriteImageState>>;
+    /** Optional tag value; null indicates no tag. */
+    readonly tag: TTag | null;
+}
+
+/**
+ * Back easing definition.
+ */
+export declare interface SpriteEasingBack {
+    readonly type: 'back';
+    /** Overshoot factor controlling how far past the target the curve goes. Defaults to 1.70158. */
+    overshoot?: number;
+}
+
+/**
+ * Bounce easing definition.
+ */
+export declare interface SpriteEasingBounce {
+    readonly type: 'bounce';
+    /** Number of visible bounces before settling. Defaults to 3. */
+    bounces?: number;
+    /** Decay factor applied per bounce; range (0, 1]. Defaults to 0.5. */
+    decay?: number;
+}
+
+/**
+ * Cubic easing definition.
+ */
+export declare interface SpriteEasingCubic {
+    readonly type: 'cubic';
+    /** Direction of the cubic curve. Defaults to in-out. */
+    mode?: 'in' | 'out' | 'in-out';
+}
+
+/**
+ * Ease easing definition.
+ */
+export declare interface SpriteEasingEase {
+    readonly type: 'ease';
+    /** Power applied to the easing curve. Defaults to 3. */
+    power?: number;
+    /** Direction of the easing curve. Defaults to in-out. */
+    mode?: 'in' | 'out' | 'in-out';
+}
+
+/**
+ * Exponential easing definition.
+ */
+export declare interface SpriteEasingExponential {
+    readonly type: 'exponential';
+    /** Growth rate used by the exponential curve. Defaults to 5. */
+    exponent?: number;
+    /** Direction of the exponential curve. Defaults to in-out. */
+    mode?: 'in' | 'out' | 'in-out';
+}
+
+/**
+ * Linear easing definition.
+ */
+export declare interface SpriteEasingLinear {
+    readonly type: 'linear';
+}
+
+/**
+ * Union of supported easing parameters.
+ */
+export declare type SpriteEasingParam = SpriteEasingLinear | SpriteEasingEase | SpriteEasingExponential | SpriteEasingQuadratic | SpriteEasingCubic | SpriteEasingSine | SpriteEasingBounce | SpriteEasingBack;
+
+/**
+ * Quadratic easing definition.
+ */
+export declare interface SpriteEasingQuadratic {
+    readonly type: 'quadratic';
+    /** Direction of the quadratic curve. Defaults to in-out. */
+    mode?: 'in' | 'out' | 'in-out';
+}
+
+/**
+ * Sine easing definition.
+ */
+export declare interface SpriteEasingSine {
+    readonly type: 'sine';
+    /** Direction of the sine ease. Defaults to in-out. */
+    mode?: 'in' | 'out' | 'in-out';
+    /** Multiplier applied to the sine amplitude. Defaults to 1. */
+    amplitude?: number;
+}
+
+/**
+ * Easing types.
+ */
+export declare type SpriteEasingType = SpriteEasingParam['type'];
+
+/**
+ * Initial attributes that define a sprite image.
+ */
+export declare interface SpriteImageDefinitionInit {
+    /** Image ID to render. */
+    imageId: string;
+    /** Rendering mode. Defaults to surface. */
+    mode?: SpriteMode;
+    /** Opacity multiplier. Defaults to 1.0. */
+    opacity?: number;
+    /** Real-world meters represented by one pixel. Defaults to 1.0. */
+    scale?: number;
+    /** Anchor within the image. Defaults to [0.0, 0.0]. */
+    anchor?: SpriteAnchor;
+    /** Offset distance in meters from the sprite coordinate. Defaults to 0. */
+    offsetMeters?: number;
+    /** Offset angle in degrees. Defaults to 0. */
+    offsetDeg?: number;
+    /** Optional border rendered around the image. */
+    border?: SpriteImageLineAttribute;
+    /** Optional leader line rendered toward the origin image. */
+    leaderLine?: SpriteImageLineAttribute;
+    /**
+     * Determines which coordinate to anchor against.
+     * - Omitted: use "the sprite" base coordinate.
+     * - Provided: use the referenced image's anchor and offset (resolving references recursively).
+     */
+    originLocation?: SpriteImageOriginLocation;
+    /**
+     * Additional rotation in degrees. Defaults to 0.
+     * Billboard: clockwise degrees relative to the screen with 0 deg up.
+     * Surface: clockwise degrees from geographic north.
+     */
+    rotateDeg?: number;
+    /**
+     * Enables auto-rotation based on movement. Defaults to true in surface mode and false in billboard mode.
+     */
+    autoRotation?: boolean;
+    /**
+     * Minimum distance in meters before auto-rotation updates. Defaults to 20; <= 0 updates immediately.
+     */
+    autoRotationMinDistanceMeters?: number;
+    /**
+     * Optional interpolation settings.
+     */
+    interpolation?: SpriteImageInterpolationOptions;
+}
+
+/**
+ * Helper for bulk initializing sprite images.
+ */
+export declare interface SpriteImageDefinitionInitEntry extends SpriteImageDefinitionInit {
+    /** Sub-layer identifier. */
+    subLayer: number;
+    /**
+     * Order within the sub-layer; higher values render in front.
+     */
+    order: number;
+}
+
+/**
+ * Update payload for a sprite image. Properties left undefined are ignored.
+ */
+export declare interface SpriteImageDefinitionUpdate {
+    /** Image ID to render. */
+    imageId?: string;
+    /** Rendering mode. */
+    mode?: SpriteMode;
+    /** Opacity multiplier. */
+    opacity?: number;
+    /** Real-world meters represented by one pixel. */
+    scale?: number;
+    /** Anchor within the image. */
+    anchor?: SpriteAnchor;
+    /** Offset distance in meters from the sprite coordinate. */
+    offsetMeters?: number;
+    /** Offset angle in degrees. */
+    offsetDeg?: number;
+    /** Border rendered around the image. Specify null to remove. */
+    border?: SpriteImageLineAttribute | null;
+    /** Leader line rendered toward the origin image. Specify null to remove. */
+    leaderLine?: SpriteImageLineAttribute | null;
+    /** Additional rotation in degrees. */
+    rotateDeg?: number;
+    /** Enables auto-rotation toward the travel direction. */
+    autoRotation?: boolean;
+    /** Minimum distance in meters before auto-rotation updates. */
+    autoRotationMinDistanceMeters?: number;
+    /** Optional interpolation settings. */
+    interpolation?: SpriteImageInterpolationOptions;
+}
+
+/**
+ * Update entry describing a sprite image modification.
+ */
+export declare interface SpriteImageDefinitionUpdateEntry {
+    /** Target sub-layer that contains the image. */
+    subLayer: number;
+    /** Order slot within the sub-layer. */
+    order: number;
+    /** Update payload, or `null` to remove the image. */
+    image: SpriteImageDefinitionUpdate | null;
+}
+
+/**
+ * Offset with interpolation metadata for both distance and heading.
+ */
+export declare interface SpriteImageInterpolatedOffset {
+    /** Distance from the anchor in meters. */
+    readonly offsetMeters: SpriteInterpolatedValues<number>;
+    /** Heading describing the offset direction in degrees. */
+    readonly offsetDeg: SpriteInterpolatedValues<number>;
+}
+
+/**
+ * Interpolation configuration.
+ */
+export declare interface SpriteImageInterpolationOptions {
+    /** Interpolation settings for finalRotateDeg; `null` will disable interpolation. */
+    finalRotateDeg?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for offset.offsetDeg; `null` will disable interpolation. */
+    offsetDeg?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for offset.offsetMeters; `null` will disable interpolation. */
+    offsetMeters?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for finalOpacity; `null` will disable interpolation. */
+    finalOpacity?: SpriteInterpolationOptions | null;
+}
+
+/**
+ * Line attribute.
+ */
+export declare interface SpriteImageLineAttribute {
+    /** CSS color string. Defaults to red. */
+    color?: string;
+    /** Line width in meters. Defaults to 1. */
+    widthMeters?: number;
+}
+
+/**
+ * Resolved line attribute state.
+ */
+export declare interface SpriteImageLineAttributeState {
+    /** CSS color string applied to the line. */
+    readonly color: string;
+    /** Line width in meters. */
+    readonly widthMeters: number;
+}
+
+/**
+ * Reference to another image's anchor for positioning.
+ */
+export declare interface SpriteImageOriginLocation {
+    /**
+     * Sub-layer identifier.
+     */
+    subLayer: number;
+    /**
+     * Order within the sub-layer; higher values render in front.
+     */
+    order: number;
+    /**
+     * Use the referenced image's anchor-adjusted position when true. Defaults to the pre-anchor base point.
+     */
+    useResolvedAnchor?: boolean;
+}
+
+/**
+ * Options accepted by {@link SpriteLayerInterface.registerImage}.
+ */
+export declare interface SpriteImageRegisterOptions {
+    /** Target width in CSS pixels. When only one dimension is supplied, the aspect ratio is preserved if known. */
+    readonly width?: number;
+    /** Target height in CSS pixels. When only one dimension is supplied, the aspect ratio is preserved if known. */
+    readonly height?: number;
+    /** Resampling quality used during rasterization. */
+    readonly resizeQuality?: ResizeQuality;
+    /** SVG-specific configuration. */
+    readonly svg?: SpriteImageSvgOptions;
+}
+
+/**
+ * Sprite image state evaluated at runtime.
+ */
+export declare interface SpriteImageState {
+    /** Sub-layer index the image belongs to. */
+    readonly subLayer: number;
+    /** Ordering slot within the sub-layer. */
+    readonly order: number;
+    /** Identifier of the registered image or glyph. */
+    readonly imageId: string;
+    /** Rendering mode applied to the image. */
+    readonly mode: SpriteMode;
+    /** Scale factor converting pixels to meters. */
+    readonly scale: number;
+    /** Anchor coordinates resolved for the image. */
+    readonly anchor: Readonly<SpriteAnchor>;
+    /** User-specified rotation angle. */
+    readonly rotateDeg: number;
+    /** User-specified opacity. */
+    readonly opacity: number;
+    /** Offset applied relative to the anchor point. */
+    readonly offset: SpriteImageInterpolatedOffset;
+    /** Optional border rendered around the image. */
+    readonly border: SpriteImageLineAttributeState | undefined;
+    /** Optional leader line rendered toward the origin image. */
+    readonly leaderLine: SpriteImageLineAttributeState | undefined;
+    /** Indicates whether auto-rotation is active. */
+    readonly autoRotation: boolean;
+    /** Minimum travel distance before auto-rotation updates. */
+    readonly autoRotationMinDistanceMeters: number;
+    /** Rotation angle applied when rendering (includes auto-rotation). */
+    readonly finalRotateDeg: SpriteInterpolatedValues<number>;
+    /** Opacity applied when rendering (includes multipliers). */
+    readonly finalOpacity: SpriteInterpolatedValues<number>;
+    /** Optional reference to another image used for anchoring. */
+    readonly originLocation: Readonly<SpriteImageOriginLocation> | undefined;
+}
+
+/**
+ * Options used when registering SVG images.
+ */
+export declare interface SpriteImageSvgOptions {
+    /** Treat the resource as SVG even when the MIME type is missing or incorrect. */
+    readonly assumeSvg?: boolean;
+    /** Enables parsing of the SVG markup to detect intrinsic sizing. Defaults to true for SVG images. */
+    readonly inspectSize?: boolean;
+    /**
+     * Uses the SVG viewBox dimensions as the raster size when width/height attributes are missing.
+     * When disabled (default), such SVGs fail to load instead of inferring a size.
+     */
+    readonly useViewBoxDimensions?: boolean;
+}
+
+/**
+ * Parameters required to construct a new sprite.
+ *
+ * @template TTag Tag type.
+ */
+export declare interface SpriteInit<TTag> {
+    /** Whether the sprite starts enabled. Defaults to true. */
+    isEnabled?: boolean;
+    /** Initial location. */
+    location: SpriteLocation;
+    /**
+     * Marks the sprite as invalidated initially, causing interpolation parameters to be
+     * ignored until the first update drives the value again.
+     */
+    invalidate?: boolean;
+    /**
+     * Pseudo LOD threshold for the sprite. When the camera distance exceeds this value,
+     * all images attached to the sprite become invisible.
+     */
+    visibilityDistanceMeters?: number;
+    /**
+     * Default interpolation settings applied to initial location updates until overridden.
+     */
+    interpolation?: SpriteInterpolationOptions;
+    /**
+     * Multiplier applied to every image opacity belonging to the sprite. Defaults to 1.0.
+     */
+    opacityMultiplier?: number;
+    /** Array of zero or more images. */
+    images: SpriteImageDefinitionInitEntry[];
+    /** Optional tag value; null or omission means no tag. */
+    tag?: TTag | null;
+}
+
+/**
+ * Batch payload accepted by addSprites. Supports both record and array inputs.
+ *
+ * @template TTag Tag type.
+ */
+export declare type SpriteInitCollection<TTag> = Record<string, SpriteInit<TTag>> | readonly SpriteInitEntry<TTag>[];
+
+/**
+ * Entry for batch sprite creation, pairing a sprite identifier with its initial settings.
+ *
+ * @template TTag Tag type.
+ */
+export declare interface SpriteInitEntry<TTag> extends SpriteInit<TTag> {
+    /** Sprite identifier. */
+    spriteId: string;
+}
+
+/**
+ * Interpolated values.
+ * @param TValue - Value type.
+ */
+export declare interface SpriteInterpolatedValues<TValue> {
+    /** Current time value. */
+    readonly current: TValue;
+    /** Requested value. */
+    readonly from: TValue | undefined;
+    /** Will be reached value. */
+    readonly to: TValue | undefined;
+    /** Marks whether the value was invalidated due to visibility changes. */
+    readonly invalidated: boolean | undefined;
+}
+
+/**
+ * Defines interpolation modes.
+ */
+export declare type SpriteInterpolationMode = 'feedback' | 'feedforward';
+
+/**
+ * Options for interpolating values.
+ */
+export declare interface SpriteInterpolationOptions {
+    /** Interpolation mode; defaults to `feedback`. */
+    mode?: SpriteInterpolationMode;
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** Easing definition. Defaults to `linear`. */
+    easing?: SpriteEasingParam;
+}
+
+/**
+ * Runtime state describing the active interpolation between two sprite locations.
+ * Consumers reuse the same state across ticks to avoid re-allocations while animation is running.
+ */
+declare interface SpriteInterpolationState<TValue> {
+    /** Strategy used to resolve the target location (feedback or feedforward). */
+    readonly mode: SpriteInterpolationMode;
+    /** Total time allocated for the interpolation in milliseconds. */
+    readonly durationMs: number;
+    /** Easing attributes */
+    readonly easingParam: SpriteEasingParam;
+    /** Resolved easing function applied to raw progress values. */
+    readonly easingFunc: EasingFunction;
+    /** Origin sprite location cloned from the current render state. */
+    readonly from: TValue;
+    /** Destination sprite location being interpolated towards.  */
+    readonly to: TValue;
+    /** */
+    readonly pathTarget?: TValue;
+    /** Epoch millisecond when the interpolation started, or -1 when uninitialized. */
+    startTimestamp: number;
+}
+
+/**
+ * Calculation variant. It is internal calculation methods.
+ */
+export declare type SpriteLayerCalculationVariant = 'simd-mt' | 'simd' | 'nosimd' | 'disabled';
+
+/**
+ * Event dispatched when a sprite is clicked or tapped.
+ *
+ * @template TTag Tag type stored on sprites.
+ */
+export declare interface SpriteLayerClickEvent<TTag> {
+    /** Discriminated event type. */
+    readonly type: 'spriteclick';
+    /** Snapshot of the sprite that was hit, or `undefined` when it no longer exists. */
+    readonly sprite: SpriteCurrentState<TTag> | undefined;
+    /** Sprite image that received the interaction, or `undefined` when missing. */
+    readonly image: SpriteImageState | undefined;
+    /** Screen position of the interaction. */
+    readonly screenPoint: SpriteScreenPoint;
+    /** Original DOM event. */
+    readonly originalEvent: MouseEvent | PointerEvent | TouchEvent;
+}
+
+/**
+ * Event listener callback.
+ *
+ * @template TTag Tag type stored on sprites.
+ * @template K Event key from {@link SpriteLayerEventMap}.
+ * @param {SpriteLayerEventMap<TTag>[K]} event - Event payload dispatched by SpriteLayer.
+ * @returns {void}
+ */
+export declare type SpriteLayerEventListener<TTag, K extends keyof SpriteLayerEventMap<TTag>> = (event: SpriteLayerEventMap<TTag>[K]) => void;
+
+/**
+ * Map of events emitted by SpriteLayer.
+ *
+ * @template TTag Tag type stored on sprites.
+ */
+export declare interface SpriteLayerEventMap<TTag> {
+    /** Event fired when a sprite image is clicked. */
+    readonly spriteclick: SpriteLayerClickEvent<TTag>;
+    /** Event fired when a sprite image is hovered. */
+    readonly spritehover: SpriteLayerHoverEvent<TTag>;
+}
+
+/**
+ * SpriteLayer host options.
+ */
+export declare interface SpriteLayerHostOptions {
+    /**
+     * Calculation variant. Default is `simd`.
+     * Use `simd-mt` to enable pthread/SIMD wasm when `SharedArrayBuffer` is available
+     * (i.e. cross-origin isolated contexts) and fall back to the other variants otherwise.
+     */
+    readonly variant?: SpriteLayerCalculationVariant;
+    /**
+     * Wasm runtime module base URL path. Default is `/wasm`
+     */
+    readonly wasmBaseUrl?: string;
+}
+
+/**
+ * Event dispatched when a sprite is hovered by a pointing device.
+ *
+ * @template TTag Tag type stored on sprites.
+ */
+export declare interface SpriteLayerHoverEvent<TTag> {
+    /** Discriminated event type. */
+    readonly type: 'spritehover';
+    /** Snapshot of the sprite that was hit, or `undefined` when it no longer exists. */
+    readonly sprite: SpriteCurrentState<TTag> | undefined;
+    /** Sprite image that received the interaction, or `undefined` when missing. */
+    readonly image: SpriteImageState | undefined;
+    /** Screen position of the interaction. */
+    readonly screenPoint: SpriteScreenPoint;
+    /** Original hover-capable DOM event. */
+    readonly originalEvent: MouseEvent | PointerEvent;
+}
+
+/**
+ * MapLibre layer interface for SpriteLayer.
+ * Renders large numbers of sprites and supports high-frequency updates.
+ *
+ * @template TTag Sprite tag type.
+ */
+export declare interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
+    /**
+     * Registers an image or glyph so it can be referenced by sprite images.
+     *
+     * @param {string} imageId - Unique image identifier.
+     * @param {string | ImageBitmap} image - Image source (URL or ImageBitmap) to upload.
+     * @param {SpriteImageRegisterOptions | undefined} options - Optional SVG handling controls.
+     * @returns {Promise<boolean>} Resolves to `true` when the image was registered; `false` if the ID already existed.
+     */
+    readonly registerImage: (imageId: string, image: string | ImageBitmap, options?: SpriteImageRegisterOptions) => Promise<boolean>;
+    /**
+     * Registers a text glyph texture for later use.
+     *
+     * @param {string} textGlyphId - Unique identifier for the text glyph.
+     * @param {string} text - Text content to render.
+     * @param {SpriteTextGlyphDimensions} dimensions - Glyph sizing options.
+     * @param {SpriteTextGlyphOptions | undefined} options - Optional styling information.
+     * @returns {Promise<boolean>} Resolves to `true` when the glyph was registered; `false` if the ID already existed.
+     */
+    readonly registerTextGlyph: (textGlyphId: string, text: string, dimensions: SpriteTextGlyphDimensions, options?: SpriteTextGlyphOptions) => Promise<boolean>;
+    /**
+     * Removes a previously registered image or glyph.
+     *
+     * @param {string} imageId - Identifier of the image to remove.
+     * @returns {boolean} `true` when the image existed and was removed.
+     */
+    readonly unregisterImage: (imageId: string) => boolean;
+    /**
+     * Removes every registered image and glyph, releasing associated GPU resources.
+     *
+     * @returns {void}
+     */
+    readonly unregisterAllImages: () => void;
+    /**
+     * Returns all currently registered image IDs.
+     *
+     * @returns {string[]} Array of registered image identifiers.
+     */
+    readonly getAllImageIds: () => string[];
+    /**
+     * Adds a sprite to the layer.
+     *
+     * @param {string} spriteId - Unique sprite identifier.
+     * @param {SpriteInit<TTag>} init - Initial sprite configuration.
+     * @returns {boolean} `true` when the sprite was inserted; `false` if the ID already existed.
+     */
+    readonly addSprite: (spriteId: string, init: SpriteInit<TTag>) => boolean;
+    /**
+     * Adds multiple sprites in one call.
+     *
+     * @param {SpriteInitCollection<TTag>} sprites - Sprite definitions keyed by ID or supplied as entries.
+     * @returns {number} Number of sprites that were inserted.
+     */
+    readonly addSprites: (sprites: SpriteInitCollection<TTag>) => number;
+    /**
+     * Removes a sprite.
+     *
+     * @param {string} spriteId - Identifier of the sprite to remove.
+     * @returns {void}
+     */
+    readonly removeSprite: (spriteId: string) => void;
+    /**
+     * Removes multiple sprites.
+     *
+     * @param {readonly string[]} spriteIds - Identifiers of the sprites to remove.
+     * @returns {number} Number of sprites that were removed.
+     */
+    readonly removeSprites: (spriteIds: readonly string[]) => number;
+    /**
+     * Removes all sprites.
+     *
+     * @returns {number} Number of sprites that were removed.
+     */
+    readonly removeAllSprites: () => number;
+    /**
+     * Retrieves the current state for a sprite.
+     *
+     * @param {string} spriteId - Identifier of the sprite.
+     * @returns {SpriteCurrentState<TTag> | undefined} Current state or `undefined` when not found.
+     */
+    readonly getSpriteState: (spriteId: string) => SpriteCurrentState<TTag> | undefined;
+    /**
+     * Returns all sprite IDs currently managed by the layer.
+     *
+     * @returns {string[]} Array of sprite identifiers.
+     */
+    readonly getAllSpriteIds: () => string[];
+    /**
+     * Attaches an image definition to a sprite.
+     *
+     * @param {string} spriteId - Target sprite identifier.
+     * @param {number} subLayer - Sub-layer index.
+     * @param {number} order - Order slot within the sub-layer.
+     * @param {SpriteImageDefinitionInit} imageInit - Image definition to insert.
+     * @returns {boolean} `true` when the image slot was empty and the definition applied.
+     */
+    readonly addSpriteImage: (spriteId: string, subLayer: number, order: number, imageInit: SpriteImageDefinitionInit) => boolean;
+    /**
+     * Updates an image assigned to a sprite.
+     *
+     * @param {string} spriteId - Target sprite identifier.
+     * @param {number} subLayer - Sub-layer index containing the image.
+     * @param {number} order - Order slot within the sub-layer.
+     * @param {SpriteImageDefinitionUpdate} imageUpdate - Update payload.
+     * @returns {boolean} `true` when the image existed and was updated.
+     */
+    readonly updateSpriteImage: (spriteId: string, subLayer: number, order: number, imageUpdate: SpriteImageDefinitionUpdate) => boolean;
+    /**
+     * Removes an image from a sprite.
+     *
+     * @param {string} spriteId - Target sprite identifier.
+     * @param {number} subLayer - Sub-layer index containing the image.
+     * @param {number} order - Order slot within the sub-layer.
+     * @returns {boolean} `true` when the image existed and was removed.
+     */
+    readonly removeSpriteImage: (spriteId: string, subLayer: number, order: number) => boolean;
+    /**
+     * Removes all images attached to the specified sprite.
+     *
+     * @param {string} spriteId - Identifier of the sprite whose images should be removed.
+     * @returns {number} Number of images that were removed.
+     */
+    readonly removeAllSpriteImages: (spriteId: string) => number;
+    /**
+     * Updates a sprite with the provided payload.
+     *
+     * @param {string} spriteId - Target sprite identifier.
+     * @param {SpriteUpdateEntry<TTag>} update - Update payload describing property changes.
+     * @returns {boolean} `true` when the sprite was found and updated.
+     */
+    readonly updateSprite: (spriteId: string, update: SpriteUpdateEntry<TTag>) => boolean;
+    /**
+     * Adds, updates, or removes sprites based on an arbitrary collection of source items.
+     *
+     * @param {readonly TSourceItem[]} sourceItems - Source items that describe desired sprite state.
+     * @param {SpriteMutateCallbacks<TTag, TSourceItem>} mutator - Callbacks responsible for creation and modification.
+     * @returns {number} Number of sprites that changed. Counts each `add` that returns a non-null
+     * initializer and each `modify` that either invoked the updater helper or returned `'remove'`.
+     */
+    readonly mutateSprites: <TSourceItem extends SpriteMutateSourceItem>(sourceItems: readonly TSourceItem[], mutator: SpriteMutateCallbacks<TTag, TSourceItem>) => number;
+    /**
+     * Iterates over each sprite and allows modifications through a callback.
+     *
+     * @param {(sprite: SpriteCurrentState<TTag>, update: SpriteUpdaterEntry<TTag>) => boolean} updater - Callback invoked for each sprite. Return `false` to stop iteration early.
+     * @returns {number} Number of sprites that were updated.
+     */
+    readonly updateForEach: (updater: (sprite: SpriteCurrentState<TTag>, update: SpriteUpdaterEntry<TTag>) => boolean) => number;
+    /**
+     * Controls entire interpolation Calculation.
+     * When `false`, interpolation halts immediately and resumes smoothly from the paused state when re-enabled.
+     * @param moveable - Continuous calculation for movement interpolation when value is true.
+     */
+    readonly setInterpolationCalculation: (moveable: boolean) => void;
+    /**
+     * Enables or disables hit-test.
+     *
+     * @param {boolean} detect - When false, hit testing is skipped.
+     */
+    readonly setHitTestDetection: (detect: boolean) => void;
+    /**
+     * Starts tracking a sprite so the map recenters on it every animation frame.
+     * When `trackRotation` is true (default), the sprite's final rotation follows the map bearing.
+     *
+     * @param {string} spriteId - Identifier of the sprite to track.
+     * @param {boolean} [trackRotation=true] - Whether to align the sprite's rotation to the map bearing.
+     * @returns {void}
+     */
+    readonly trackSprite: (spriteId: string, trackRotation?: boolean) => void;
+    /**
+     * Stops tracking any sprite previously targeted via {@link trackSprite}.
+     *
+     * @returns {void}
+     */
+    readonly untrackSprite: () => void;
+    /**
+     * Adds an event listener.
+     *
+     * @param {K} type - Event name.
+     * @param {SpriteLayerEventListener<TTag, K>} listener - Listener callback.
+     * @returns {void}
+     */
+    readonly on: <K extends keyof SpriteLayerEventMap<TTag>>(type: K, listener: SpriteLayerEventListener<TTag, K>) => void;
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param {K} type - Event name.
+     * @param {SpriteLayerEventListener<TTag, K>} listener - Listener callback to remove.
+     * @returns {void}
+     */
+    readonly off: <K extends keyof SpriteLayerEventMap<TTag>>(type: K, listener: SpriteLayerEventListener<TTag, K>) => void;
+}
+
+/**
+ * Options accepted when creating a SpriteLayer.
+ */
+export declare interface SpriteLayerOptions {
+    /** Optional layer identifier supplied to MapLibre. */
+    id?: string;
+    /** Optional scaling controls. Default is UNLIMITED_SPRITE_SCALING_OPTIONS. */
+    spriteScaling?: SpriteScalingOptions;
+    /** Optional texture filtering configuration. */
+    textureFiltering?: SpriteTextureFilteringOptions;
+}
+
+/**
+ * Base coordinate for the sprite. All images within the sprite are positioned relative to this location.
+ */
+export declare interface SpriteLocation {
+    /** Longitude in degrees. */
+    lng: number;
+    /** Latitude in degrees. */
+    lat: number;
+    /** Elevation or virtual height. Defaults to 0 and is currently unused. */
+    z?: number;
+}
+
+/**
+ * Represents a projected three dimensional position.
+ * `MercatorCoordinate` uses the web mercator projection ([EPSG:3857](https://epsg.io/3857)) with slightly different units:
+ * - the size of 1 unit is the width of the projected world instead of the "mercator meter"
+ * - the origin of the coordinate space is at the north-west corner instead of the middle
+ */
+declare interface SpriteMercatorCoordinate {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+
+/**
+ * Sprite rendering modes.
+ * Billboard: Image always faces the viewport, suited for HUD-style elements.
+ * Surface: Image lies parallel to the map surface, suited for dynamic markers on the map.
+ */
+export declare type SpriteMode = 'billboard' | 'surface';
+
+/**
+ * Result flags returned by `mutateSprites` callbacks.
+ * - `'notremove'`: Keep the sprite after applying any modifications.
+ * - `'remove'`: Remove the sprite from the layer.
+ */
+export declare type SpriteModifierResult = 'notremove' | 'remove';
+
+/**
+ * Callbacks invoked by `mutateSprites` for each source item.
+ *
+ * @template TTag Sprite tag type stored by the layer.
+ * @template TSourceItem Source item type that satisfies {@link SpriteMutateSourceItem}.
+ */
+export declare interface SpriteMutateCallbacks<TTag, TSourceItem extends SpriteMutateSourceItem> {
+    /**
+     * Invoked when the sprite ID from the source item does not yet exist.
+     * Return a populated {@link SpriteInit} when the sprite should be added; return `undefined`
+     * (or `null`) to skip creation.
+     *
+     * @param sourceItem Source item that produced the sprite ID.
+     * @returns Sprite initializer to insert, or `undefined`/`null` to skip.
+     */
+    add: (sourceItem: TSourceItem) => SpriteInit<TTag> | null | undefined;
+    /**
+     * Invoked when the sprite ID already exists on the layer.
+     * Use `update` to mutate sprite properties or images; return `'remove'` to delete the sprite instead.
+     *
+     * @param sourceItem Source item that produced the sprite ID.
+     * @param sprite Current sprite state snapshot.
+     * @param update Helper exposing the same operations as {@link SpriteUpdaterEntry}.
+     * @returns `'remove'` to delete the sprite; otherwise `'notremove'`.
+     */
+    modify: (sourceItem: TSourceItem, sprite: SpriteCurrentState<TTag>, update: SpriteUpdaterEntry<TTag>) => SpriteModifierResult;
+}
+
+/** Source items supplied to `mutateSprites` must expose the target sprite ID. */
+export declare interface SpriteMutateSourceItem {
+    /** Identifier of the sprite targeted by the source item. */
+    readonly spriteId: string;
+}
+
+/**
+ * Encode/Decode interface for a (subLayer, order) pair into a compact numeric key.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ */
+declare interface SpriteOriginReference {
+    /**
+     * Encodes a (subLayer, order) pair into a compact numeric key.
+     * @param subLayer Sub-layer identifier within the sprite.
+     * @param order Order slot inside the sub-layer.
+     * @returns Encoded origin reference key.
+     */
+    readonly encodeKey: (subLayer: number, order: number) => SpriteOriginReferenceKey;
+    /**
+     * Decodes an origin reference key back into the sub-layer and order pair.
+     * @param key Encoded origin reference key.
+     * @returns `subLayer` and `order` components; when the key is invalid, both values are set to `-1`.
+     */
+    readonly decodeKey: (key: SpriteOriginReferenceKey) => {
+        readonly subLayer: number;
+        readonly order: number;
+    };
+}
+
+/**
+ * Index into the render target bucket pointing at the resolved origin image.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ *          When no origin is assigned or the reference could not be resolved,
+ *          the value will be {@link SPRITE_ORIGIN_REFERENCE_INDEX_NONE}.
+ */
+declare type SpriteOriginReferenceIndex = number;
+
+/**
+ * Encoded pointer representing the target of an origin reference.
+ * @remarks It is used for (wasm) interoperability for image identity.
+ *          The high bits encode the sub-layer while the low bits encode the order slot.
+ */
+declare type SpriteOriginReferenceKey = number;
+
+/**
+ * Represents a point on anonymous-unit space.
+ */
+export declare interface SpritePoint {
+    /** Horizontal (X axis) coordinate. */
+    readonly x: number;
+    /** Vertical (Y axis) coordinate. */
+    readonly y: number;
+}
+
+/**
+ * Options controlling distance-aware scaling.
+ */
+export declare interface SpriteScalingOptions {
+    /**
+     * Overrides the baseline meters-per-pixel ratio.
+     * We strongly recommend specifying the default value of 1, as this value affects all calculations.
+     */
+    metersPerPixel?: number;
+    /**
+     * Distance (meters) from the camera at which sprites stop growing when getting closer.
+     * Set to 0 or omit to disable the near-distance clamp.
+     */
+    minScaleDistanceMeters?: number;
+    /**
+     * Distance (meters) from the camera at which sprites stop shrinking when moving away.
+     * Set to 0 or omit to disable the far-distance clamp.
+     */
+    maxScaleDistanceMeters?: number;
+}
+
+/**
+ * Represents a point in screen space.
+ */
+export declare type SpriteScreenPoint = SpritePoint;
+
+/**
+ * Border sides that can be rendered for a text glyph outline.
+ */
+export declare type SpriteTextGlyphBorderSide = 'top' | 'right' | 'bottom' | 'left';
+
+/**
+ * Additional size options accepted by registerTextGlyph.
+ */
+export declare type SpriteTextGlyphDimensions = {
+    readonly lineHeightPixel: number;
+    readonly maxWidthPixel?: never;
+} | {
+    readonly maxWidthPixel: number;
+    readonly lineHeightPixel?: never;
+};
+
+/**
+ * Horizontal alignment options for text glyphs.
+ */
+export declare type SpriteTextGlyphHorizontalAlign = 'left' | 'center' | 'right';
+
+/**
+ * Text glyph appearance options.
+ */
+export declare interface SpriteTextGlyphOptions {
+    /** Font family name. */
+    fontFamily?: string;
+    /** CSS font-weight value. */
+    fontWeight?: string;
+    /** CSS font-style value. */
+    fontStyle?: 'normal' | 'italic';
+    /** Text fill color. */
+    color?: string;
+    /** Letter spacing in pixels. */
+    letterSpacingPixel?: number;
+    /** Background color applied behind the text. */
+    backgroundColor?: string;
+    /** Padding around the glyph. */
+    paddingPixel?: SpriteTextGlyphPaddingPixel;
+    /** Outline color. */
+    borderColor?: string;
+    /** Outline width in pixels. */
+    borderWidthPixel?: number;
+    /** Border sides to draw; defaults to all four sides when omitted. */
+    borderSides?: readonly SpriteTextGlyphBorderSide[];
+    /** Border radius in pixels. */
+    borderRadiusPixel?: number;
+    /** Horizontal alignment of multiline text. */
+    textAlign?: SpriteTextGlyphHorizontalAlign;
+    /** It is not specified normally. Preferred font size in pixels; may shrink automatically to satisfy provided dimensions. */
+    fontSizePixelHint?: number;
+    /** Pixel ratio used when rendering the glyph; defaults to 1 and values > 1 render at higher resolution before downscaling. */
+    renderPixelRatio?: number;
+}
+
+/**
+ * Padding in pixels applied when rendering text glyphs.
+ */
+export declare type SpriteTextGlyphPaddingPixel = number | {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+
+/**
+ * Texture filtering configuration.
+ */
+export declare interface SpriteTextureFilteringOptions {
+    /** Minification filter to apply (defaults to `linear`). */
+    minFilter?: SpriteTextureMinFilter;
+    /** Magnification filter to apply (defaults to `linear`). */
+    magFilter?: SpriteTextureMagFilter;
+    /** Generates mipmaps during upload when true (defaults to `false`). */
+    generateMipmaps?: boolean;
+    /** Desired anisotropy factor (>= 1) when EXT_texture_filter_anisotropic is available. */
+    maxAnisotropy?: number;
+}
+
+/**
+ * Allowed magnification filters for sprite textures.
+ */
+export declare type SpriteTextureMagFilter = 'nearest' | 'linear';
+
+/**
+ * Allowed minification filters for sprite textures.
+ */
+export declare type SpriteTextureMinFilter = 'nearest' | 'linear' | 'nearest-mipmap-nearest' | 'nearest-mipmap-linear' | 'linear-mipmap-nearest' | 'linear-mipmap-linear';
+
+/**
+ * Sprite update entry with optional image list.
+ *
+ * @template TTag Tag type stored on the sprite.
+ */
+export declare interface SpriteUpdateEntry<TTag> extends SpriteUpdateEntryBase<TTag> {
+    /** Optional set of image updates. */
+    images?: SpriteImageDefinitionUpdateEntry[];
+}
+
+/**
+ * Base structure for sprite updates.
+ *
+ * @template TTag Tag type stored on the sprite.
+ */
+export declare interface SpriteUpdateEntryBase<TTag> {
+    /** Optional toggle to enable or disable the sprite. */
+    isEnabled?: boolean;
+    /** Optional target location for the sprite. */
+    location?: SpriteLocation;
+    /** Optional interpolation settings; `null` disables interpolation. */
+    interpolation?: SpriteInterpolationOptions | null;
+    /** Optional tag value to replace the current one; `null` clears the tag. */
+    tag?: TTag | null;
+    /**
+     * Pseudo LOD threshold for the sprite. Specify a positive finite value to enable the check,
+     * `null` to clear the current threshold, or leave `undefined` to keep the existing value.
+     */
+    visibilityDistanceMeters?: number | null;
+    /**
+     * Optional multiplier applied to every image opacity. When omitted the previous multiplier is preserved.
+     */
+    opacityMultiplier?: number;
+}
+
+/**
+ * Callback-based helper for mutating sprite state.
+ *
+ * @template TTag Tag type stored on the sprite.
+ */
+export declare interface SpriteUpdaterEntry<TTag> extends SpriteUpdateEntryBase<TTag> {
+    /**
+     * Retrieves the current image layout.
+     * @returns Structured image index (order sets each sub layers).
+     */
+    readonly getImageIndexMap: () => ReadonlyMap<number, ReadonlySet<number>>;
+    /**
+     * Adds an image definition.
+     * @param subLayer - Sub layer index.
+     * @param order - Order index.
+     * @param imageInit - Image initializer.
+     * @returns True if added.
+     */
+    readonly addImage: (subLayer: number, order: number, imageInit: SpriteImageDefinitionInit) => boolean;
+    /**
+     * Applies image updates.
+     * @param subLayer - Sub layer index.
+     * @param order - Order index.
+     * @param imageUpdate - Image updater.
+     * @returns True if updated.
+     */
+    readonly updateImage: (subLayer: number, order: number, imageUpdate: SpriteImageDefinitionUpdate) => boolean;
+    /**
+     * Removes an image slot.
+     * @param subLayer - Sub layer index.
+     * @param order - Order index.
+     * @returns True if removed.
+     */
+    readonly removeImage: (subLayer: number, order: number) => boolean;
+}
+
+/**
+ * Standard values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
+ * metersPerPixel is 1.
+ */
+export declare const STANDARD_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+
+/**
+ * East/north displacement for an individual surface corner.
+ */
+declare interface SurfaceCorner {
+    /** Eastward offset in meters relative to the base center. */
+    readonly east: number;
+    /** Northward offset in meters relative to the base center. */
+    readonly north: number;
+}
+
+/**
+ * Corner model describing world displacements and resulting geographic coordinates for shader validation.
+ */
+declare interface SurfaceShaderCornerState extends SpriteLocation, SurfaceCorner {
+}
+
+/**
+ * Aggregated inputs required to reproduce surface geometry on the GPU.
+ */
+declare interface SurfaceShaderInputs {
+    readonly mercatorCenter: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    };
+    readonly worldToMercatorScale: Readonly<SurfaceCorner>;
+    readonly halfSizeMeters: Readonly<SurfaceCorner>;
+    readonly anchor: Readonly<SpriteAnchor>;
+    readonly offsetMeters: Readonly<SurfaceCorner>;
+    readonly sinCos: {
+        readonly sin: number;
+        readonly cos: number;
+    };
+    readonly totalRotateDeg: number;
+    readonly depthBiasNdc: number;
+    readonly centerDisplacement: Readonly<SurfaceCorner>;
+    readonly baseLngLat: Readonly<SpriteLocation>;
+    readonly displacedCenter: Readonly<SpriteLocation>;
+    readonly scaleAdjustment: number;
+    readonly corners: readonly Readonly<SurfaceShaderCornerState>[];
+    clipCenter: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    };
+    clipBasisEast: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    };
+    clipBasisNorth: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    };
+    clipCorners: ReadonlyArray<{
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+        readonly w: number;
+    }>;
+}
+
+export declare class SvgSizeResolutionError extends Error implements Error {
+    readonly code: SvgSizeResolutionErrorCode;
+    constructor(message: string, code: SvgSizeResolutionErrorCode);
+}
+
+export declare type SvgSizeResolutionErrorCode = 'size-missing' | 'viewbox-disabled' | 'invalid-dimensions';
+
+/**
+ * Unlimited (default) values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
+ * metersPerPixel is 1.
+ */
+export declare const UNLIMITED_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+
+export { }