maplibre-gl-layers 0.18.0 → 0.19.0

package/dist/internalTypes.d.ts

@@ -1,14 +1,14 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
-import { SpriteMode, SpriteAnchor, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, SpriteScreenPoint, SpritePoint, SpriteEasingParam, SpriteImageLineAttributeState, SpriteImageState, SpriteInterpolatedValues, SpriteImageInterpolatedOffset } from './types';
+import { SpriteMode, SpriteAnchor, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, SpriteScreenPoint, SpritePoint, SpriteEasingParam, SpriteImageLineAttributeState, SpriteImageState, SpriteInterpolatedValues, SpriteImageInterpolatedOffset, SpriteCurrentState } from './types';
 import { ResolvedSpriteScalingOptions, SurfaceCorner } from './utils/math';
 export interface Releasable {
     readonly release: () => void;
@@ -245,8 +245,6 @@ export interface PrepareDrawSpriteImageParamsBase {
     readonly imageResources: ImageResourceTable;
     readonly imageHandleBuffers: Readonly<ImageHandleBuffers>;
     readonly baseMetersPerPixel: number;
-    readonly spriteMinPixel: number;
-    readonly spriteMaxPixel: number;
     readonly drawingBufferWidth: number;
     readonly drawingBufferHeight: number;
     readonly pixelRatio: number;
@@ -256,7 +254,6 @@ export interface PrepareDrawSpriteImageParamsBefore<TTag> extends PrepareDrawSpr
     readonly bucket: readonly Readonly<RenderTargetEntryLike<TTag>>[];
     readonly bucketBuffers: Readonly<RenderTargetBucketBuffers>;
     readonly resolvedScaling: ResolvedSpriteScalingOptions;
-    readonly zoomScaleFactor: number;
 }
 export interface PrepareDrawSpriteImageParamsAfter extends PrepareDrawSpriteImageParamsBase {
     readonly identityScaleX: number;
@@ -310,8 +307,6 @@ export interface PreparedDrawSpriteImageParams<T> {
  */
 export interface RenderInterpolationFrameContext {
     readonly baseMetersPerPixel: number;
-    readonly spriteMinPixel: number;
-    readonly spriteMaxPixel: number;
 }
 /**
  * Parameters consumed when processing sprite interpolations.
@@ -430,30 +425,8 @@ export interface SpriteInterpolationState<TValue> {
     /** Epoch millisecond when the interpolation started, or -1 when uninitialized. */
     startTimestamp: number;
 }
-export interface DistanceInterpolationEvaluationParams {
-    readonly state: SpriteInterpolationState<number>;
-    readonly timestamp: number;
-}
-export interface DistanceInterpolationEvaluationResult {
-    readonly value: number;
-    readonly completed: boolean;
-    readonly effectiveStartTimestamp: number;
-}
-export interface DegreeInterpolationEvaluationParams {
-    readonly state: SpriteInterpolationState<number>;
-    readonly timestamp: number;
-}
-export interface DegreeInterpolationEvaluationResult {
-    readonly value: number;
-    readonly completed: boolean;
-    readonly effectiveStartTimestamp: number;
-}
-export interface SpriteInterpolationEvaluationParams {
-    readonly state: SpriteInterpolationState<SpriteLocation>;
-    readonly timestamp: number;
-}
-export interface SpriteInterpolationEvaluationResult {
-    readonly location: SpriteLocation;
+export interface SpriteInterpolationEvaluationResult<TValue> {
+    readonly value: TValue;
     readonly completed: boolean;
     readonly effectiveStartTimestamp: number;
 }
@@ -552,7 +525,7 @@ export interface ResolvedSpriteImageLineAttribute extends SpriteImageLineAttribu
     readonly rgba: RgbaColor;
 }
 /**
- * Base attributes for an image that composes a sprite.
+ * Base mutable attribute view for an image that composes a sprite.
  */
 export interface InternalSpriteImageState extends SpriteImageState {
     subLayer: number;
@@ -560,47 +533,46 @@ export interface InternalSpriteImageState extends SpriteImageState {
     imageId: string;
     imageHandle: number;
     mode: SpriteMode;
-    opacity: MutableSpriteInterpolatedValues<number>;
-    lodOpacity: number;
     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;
-    rotateDeg: MutableSpriteInterpolatedValues<number>;
-    rotationCommandDeg: number;
-    displayedRotateDeg: number;
+    finalRotateDeg: MutableSpriteInterpolatedValues<number>;
     autoRotation: boolean;
     autoRotationMinDistanceMeters: number;
-    resolvedBaseRotateDeg: number;
     originLocation: Readonly<SpriteImageOriginLocation> | undefined;
     originReferenceKey: SpriteOriginReferenceKey;
     originRenderTargetIndex: SpriteOriginReferenceIndex;
     interpolationDirty: boolean;
-    surfaceShaderInputs?: Readonly<SurfaceShaderInputs>;
-    hitTestCorners?: [
+    surfaceShaderInputs: Readonly<SurfaceShaderInputs> | undefined;
+    hitTestCorners: [
         MutableSpriteScreenPoint,
         MutableSpriteScreenPoint,
         MutableSpriteScreenPoint,
         MutableSpriteScreenPoint
-    ];
+    ] | undefined;
 }
 /**
- * Current sprite state tracked internally by the layer.
+ * Current sprite mutable state view tracked internally by the layer.
  */
-export interface InternalSpriteCurrentState<TTag> {
+export interface InternalSpriteCurrentState<TTag> extends SpriteCurrentState<TTag> {
     spriteId: string;
     handle: IdHandle;
     isEnabled: boolean;
-    visibilityDistanceMeters?: number;
+    visibilityDistanceMeters: number | undefined;
     opacityMultiplier: number;
     location: MutableSpriteInterpolatedValues<SpriteLocation>;
     images: Map<number, Map<number, InternalSpriteImageState>>;
     tag: TTag | null;
     lastAutoRotationLocation: Readonly<SpriteLocation>;
-    lastAutoRotationAngleDeg: number;
+    currentAutoRotateDeg: number;
     autoRotationInvalidated: boolean;
     interpolationDirty: boolean;
     cachedMercator: Readonly<SpriteMercatorCoordinate>;

package/dist/interpolation/degreeInterpolation.d.ts

@@ -1,15 +1,16 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 import { SpriteInterpolationOptions } from '../types';
-import { DegreeInterpolationEvaluationResult, InternalSpriteImageState, MutableSpriteInterpolation, SpriteInterpolationState } from '../internalTypes';
+import { SpriteInterpolationEvaluationResult, InternalSpriteImageState, SpriteInterpolationState } from '../internalTypes';
+import { SpriteInterpolationChannelDescriptor } from './interpolationChannels';
 /**
  * Parameters required to construct a {@link DegreeInterpolationState}.
  */
@@ -38,43 +39,10 @@ export interface CreateDegreeInterpolationStateResult {
  * @returns {CreateDegreeInterpolationStateResult} State data plus a flag indicating if animation is needed.
  */
 export declare const createDegreeInterpolationState: (params: CreateDegreeInterpolationStateParams) => CreateDegreeInterpolationStateResult;
-/**
- * Parameters describing interpolation evaluation state.
- */
-export interface EvaluateDegreeInterpolationParams {
-    /** State generated via {@link createDegreeInterpolationState}. */
-    state: SpriteInterpolationState<number>;
-    /** Timestamp in milliseconds used to sample the interpolation curve. */
-    timestamp: number;
-}
-/**
- * Result of evaluating a numeric interpolation at a specific timestamp.
- */
-export interface EvaluateDegreeInterpolationResult {
-    /** Current interpolated value (or final value after completion). */
-    readonly value: number;
-    /** Indicates whether interpolation reached the end. */
-    readonly completed: boolean;
-    /** Start timestamp applied during evaluation. */
-    readonly effectiveStartTimestamp: number;
-}
-/**
- * Evaluates a numeric interpolation against the provided timestamp.
- * @param {EvaluateDegreeInterpolationParams} params - Inputs containing interpolation state and sample timestamp.
- * @returns {EvaluateDegreeInterpolationResult} Current value, completion flag, and effective start time.
- */
-export declare const evaluateDegreeInterpolation: (params: EvaluateDegreeInterpolationParams) => EvaluateDegreeInterpolationResult;
-interface DegreeInterpolationChannelDescriptor {
-    readonly resolveInterpolation: (image: InternalSpriteImageState) => MutableSpriteInterpolation<number>;
-    readonly normalize?: (value: number) => number;
-    readonly applyValue: (image: InternalSpriteImageState, value: number) => void;
-    readonly applyFinalValue?: (image: InternalSpriteImageState, value: number) => void;
-}
-export interface DegreeInterpolationWorkItem {
-    readonly descriptor: DegreeInterpolationChannelDescriptor;
+export declare const evaluateDegreeInterpolation: (state: SpriteInterpolationState<number>, timestamp: number) => SpriteInterpolationEvaluationResult<number>;
+export interface DegreeInterpolationWorkItem extends SpriteInterpolationState<number> {
+    readonly descriptor: SpriteInterpolationChannelDescriptor;
     readonly image: InternalSpriteImageState;
-    readonly state: SpriteInterpolationState<number>;
 }
 export declare const collectDegreeInterpolationWorkItems: (image: InternalSpriteImageState, workItems: DegreeInterpolationWorkItem[]) => void;
-export declare const applyDegreeInterpolationEvaluations: (workItems: readonly DegreeInterpolationWorkItem[], evaluations: readonly DegreeInterpolationEvaluationResult[], timestamp: number) => boolean;
-export {};
+export declare const applyDegreeInterpolationEvaluations: (workItems: readonly DegreeInterpolationWorkItem[], evaluations: readonly SpriteInterpolationEvaluationResult<number>[], timestamp: number) => boolean;

package/dist/interpolation/distanceInterpolation.d.ts

@@ -1,15 +1,16 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 import { SpriteInterpolationOptions } from '../types';
-import { DistanceInterpolationEvaluationParams, DistanceInterpolationEvaluationResult, InternalSpriteImageState, MutableSpriteInterpolation, SpriteInterpolationState } from '../internalTypes';
+import { InternalSpriteImageState, SpriteInterpolationEvaluationResult, SpriteInterpolationState } from '../internalTypes';
+import { SpriteInterpolationChannelDescriptor } from './interpolationChannels';
 export interface CreateDistanceInterpolationStateParams {
     currentValue: number;
     targetValue: number;
@@ -21,25 +22,10 @@ export interface CreateDistanceInterpolationStateResult {
     readonly requiresInterpolation: boolean;
 }
 export declare const createDistanceInterpolationState: (params: CreateDistanceInterpolationStateParams) => CreateDistanceInterpolationStateResult;
-export declare const evaluateDistanceInterpolation: (params: DistanceInterpolationEvaluationParams) => DistanceInterpolationEvaluationResult;
-interface DistanceInterpolationChannelDescriptor {
-    readonly resolveInterpolation: (image: InternalSpriteImageState) => MutableSpriteInterpolation<number>;
-    readonly normalize?: (value: number) => number;
-    readonly applyValue: (image: InternalSpriteImageState, value: number) => void;
-    readonly applyFinalValue?: (image: InternalSpriteImageState, value: number) => void;
-}
-declare const DISTANCE_INTERPOLATION_CHANNELS: Record<'offsetMeters' | 'opacity', DistanceInterpolationChannelDescriptor>;
-export type DistanceInterpolationChannelDescriptorMap = typeof DISTANCE_INTERPOLATION_CHANNELS;
-export type DistanceInterpolationChannelName = keyof DistanceInterpolationChannelDescriptorMap;
-export interface DistanceInterpolationWorkItem {
-    readonly descriptor: DistanceInterpolationChannelDescriptorMap[DistanceInterpolationChannelName];
+export declare const evaluateDistanceInterpolation: (state: SpriteInterpolationState<number>, timestamp: number) => SpriteInterpolationEvaluationResult<number>;
+export interface DistanceInterpolationWorkItem extends SpriteInterpolationState<number> {
+    readonly descriptor: SpriteInterpolationChannelDescriptor;
     readonly image: InternalSpriteImageState;
-    readonly state: SpriteInterpolationState<number>;
-}
-export interface CollectDistanceInterpolationWorkItemOptions {
-    readonly includeOffsetMeters?: boolean;
-    readonly includeOpacity?: boolean;
 }
-export declare const collectDistanceInterpolationWorkItems: (image: InternalSpriteImageState, workItems: DistanceInterpolationWorkItem[], options?: CollectDistanceInterpolationWorkItemOptions) => void;
-export declare const applyDistanceInterpolationEvaluations: (workItems: readonly DistanceInterpolationWorkItem[], evaluations: readonly DistanceInterpolationEvaluationResult[], timestamp: number) => boolean;
-export {};
+export declare const collectDistanceInterpolationWorkItems: (image: InternalSpriteImageState, workItems: DistanceInterpolationWorkItem[], includeOffsetMeters: boolean, includeOpacity: boolean) => void;
+export declare const applyDistanceInterpolationEvaluations: (workItems: readonly DistanceInterpolationWorkItem[], evaluations: readonly SpriteInterpolationEvaluationResult<number>[], timestamp: number) => boolean;

package/dist/interpolation/easing.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 import { EasingFunction } from '../internalTypes';

package/dist/interpolation/interpolationChannels.d.ts

@@ -1,23 +1,33 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
-import { SpriteInterpolationOptions, SpriteImageOffset } from '../types';
-import { InternalSpriteImageState } from '../internalTypes';
+import { SpriteInterpolationOptions } from '../types';
+import { InternalSpriteImageState, MutableSpriteInterpolation } from '../internalTypes';
+export interface SpriteInterpolationChannelDescriptor {
+    readonly resolveInterpolation: (image: InternalSpriteImageState) => MutableSpriteInterpolation<number>;
+    readonly normalize?: (value: number) => number;
+    readonly applyValue: (image: InternalSpriteImageState, value: number) => void;
+    readonly applyFinalValue?: (image: InternalSpriteImageState, value: number) => void;
+}
 /**
  * Ensures the rotation channel reflects the latest targets, optionally overriding interpolation.
  */
-export declare const syncImageRotationChannel: (image: InternalSpriteImageState, optionsOverride?: SpriteInterpolationOptions | null) => void;
+export declare const syncImageRotationChannel: (image: InternalSpriteImageState, spriteAutoRotationDeg: number, optionsOverride?: SpriteInterpolationOptions | null) => void;
 /**
  * Clears any running offset angle interpolation.
  */
 export declare const clearOffsetDegInterpolation: (image: InternalSpriteImageState) => void;
+type OffsetUpdate = {
+    offsetMeters: number;
+    offsetDeg: number;
+};
 /**
  * Clears any running offset distance interpolation in meters.
  */
@@ -34,6 +44,7 @@ export type ImageInterpolationStepperId = 'rotation' | 'offsetDeg' | 'offsetMete
  */
 export interface StepSpriteImageInterpolationOptions {
     readonly skipChannels?: Partial<Record<ImageInterpolationStepperId, boolean>>;
+    readonly autoRotationDeg?: number;
 }
 export declare const stepSpriteImageInterpolations: (image: InternalSpriteImageState, timestamp: number, options?: StepSpriteImageInterpolationOptions) => boolean;
 export declare const hasActiveImageInterpolations: (image: InternalSpriteImageState) => boolean;
@@ -44,4 +55,5 @@ export interface ApplyOffsetUpdateOptions {
 /**
  * Applies offset updates across both angular and radial channels.
  */
-export declare const applyOffsetUpdate: (image: InternalSpriteImageState, nextOffset: SpriteImageOffset, options?: ApplyOffsetUpdateOptions) => void;
+export declare const applyOffsetUpdate: (image: InternalSpriteImageState, nextOffset: OffsetUpdate, options?: ApplyOffsetUpdateOptions) => void;
+export {};

package/dist/interpolation/locationInterpolation.d.ts

@@ -0,0 +1,30 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.19.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
+ */
+
+import { SpriteInterpolationOptions, SpriteLocation } from '../types';
+import { InternalSpriteCurrentState, SpriteInterpolationEvaluationResult, SpriteInterpolationState } from '../internalTypes';
+export interface CreateLocationInterpolationStateParams {
+    currentLocation: SpriteLocation;
+    lastCommandLocation?: SpriteLocation;
+    nextCommandLocation: SpriteLocation;
+    options: SpriteInterpolationOptions;
+}
+export interface CreateLocationInterpolationStateResult {
+    readonly state: SpriteInterpolationState<SpriteLocation>;
+    readonly requiresInterpolation: boolean;
+}
+export declare const createLocationInterpolationState: (params: CreateLocationInterpolationStateParams) => CreateLocationInterpolationStateResult;
+export declare const evaluateLocationInterpolation: (state: SpriteInterpolationState<SpriteLocation>, timestamp: number) => SpriteInterpolationEvaluationResult<SpriteLocation>;
+export declare const evaluateLocationInterpolationsBatch: (states: readonly SpriteInterpolationState<SpriteLocation>[], timestamp: number) => SpriteInterpolationEvaluationResult<SpriteLocation>[];
+export interface LocationInterpolationWorkItem<TTag> extends SpriteInterpolationState<SpriteLocation> {
+    readonly sprite: InternalSpriteCurrentState<TTag>;
+}
+export declare const collectLocationInterpolationWorkItems: <TTag>(sprite: InternalSpriteCurrentState<TTag>, workItems: LocationInterpolationWorkItem<TTag>[]) => void;
+export declare const applyLocationInterpolationEvaluations: <TTag>(workItems: readonly LocationInterpolationWorkItem<TTag>[], evaluations: readonly SpriteInterpolationEvaluationResult<SpriteLocation>[], timestamp: number) => boolean;

package/dist/interpolation/rotationInterpolation.d.ts

@@ -1,16 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 import { SpriteInterpolationOptions } from '../types';
 import { SpriteInterpolationState } from '../internalTypes';
-export { normalizeAngleDeg } from '../utils/math';
 /**
  * Parameters describing the rotation update request.
  */

package/dist/types.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 import { CustomLayerInterface } from 'maplibre-gl';
@@ -20,22 +20,6 @@ export interface SpriteLocation {
     /** Elevation or virtual height. Defaults to 0 and is currently unused. */
     z?: number;
 }
-/**
- * Offset describing where to place an image relative to its anchor point.
- * Specifies distance and angle from the anchor, not from the sprite's base coordinate.
- */
-export interface SpriteImageOffset {
-    /**
-     * Distance in meters from the image anchor. Zero keeps the image at the anchor point.
-     */
-    offsetMeters: number;
-    /**
-     * Angle describing the offset direction. This is not the image rotation.
-     * Billboard mode: Clockwise degrees relative to the screen, 0 deg points upward.
-     * Surface mode: Clockwise degrees from geographic north.
-     */
-    offsetDeg: number;
-}
 /**
  * Line attribute.
  */
@@ -171,14 +155,14 @@ export interface SpriteInterpolationOptions {
  * Interpolation configuration.
  */
 export interface SpriteImageInterpolationOptions {
-    /** Interpolation settings for rotateDeg; `null` will disable interpolation. */
-    rotateDeg?: SpriteInterpolationOptions | null;
+    /** 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 opacity; `null` will disable interpolation. */
-    opacity?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for finalOpacity; `null` will disable interpolation. */
+    finalOpacity?: SpriteInterpolationOptions | null;
 }
 /**
  * Sprite rendering modes.
@@ -200,8 +184,10 @@ export interface SpriteImageDefinitionInit {
     scale?: number;
     /** Anchor within the image. Defaults to [0.0, 0.0]. */
     anchor?: SpriteAnchor;
-    /** Offset from the sprite coordinate. Defaults to no offset. */
-    offset?: SpriteImageOffset;
+    /** 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. */
@@ -245,8 +231,10 @@ export interface SpriteImageDefinitionUpdate {
     scale?: number;
     /** Anchor within the image. */
     anchor?: SpriteAnchor;
-    /** Offset from the sprite coordinate. */
-    offset?: SpriteImageOffset;
+    /** 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. */
@@ -367,27 +355,24 @@ export interface SpriteImageState {
     readonly scale: number;
     /** Anchor coordinates resolved for the image. */
     readonly anchor: Readonly<SpriteAnchor>;
-    /** Opacity multiplier applied when rendering. */
-    readonly opacity: SpriteInterpolatedValues<number>;
+    /** 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;
-    /**
-     * Additional rotation in degrees with interpolation metadata.
-     * `from`/`to` are `undefined` when no rotation animation is running.
-     */
-    readonly rotateDeg: SpriteInterpolatedValues<number>;
     /** Indicates whether auto-rotation is active. */
     readonly autoRotation: boolean;
     /** Minimum travel distance before auto-rotation updates. */
     readonly autoRotationMinDistanceMeters: number;
-    /** Internal base rotation resolved for the current frame. */
-    readonly resolvedBaseRotateDeg: number;
-    /** Rotation value actually used for rendering. */
-    readonly displayedRotateDeg: 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;
 }
@@ -603,7 +588,7 @@ export interface SpriteLayerEventMap<TTag> {
  */
 export type SpriteLayerEventListener<TTag, K extends keyof SpriteLayerEventMap<TTag>> = (event: SpriteLayerEventMap<TTag>[K]) => void;
 /**
- * Options controlling zoom-to-pixel scaling.
+ * Options controlling distance-aware scaling.
  */
 export interface SpriteScalingOptions {
     /**
@@ -611,18 +596,16 @@ export interface SpriteScalingOptions {
      * We strongly recommend specifying the default value of 1, as this value affects all calculations.
      */
     metersPerPixel?: number;
-    /** Minimum zoom level before scaling adjustments apply. */
-    zoomMin?: number;
-    /** Maximum zoom level before scaling adjustments apply. */
-    zoomMax?: number;
-    /** Lower limit for scale clamping. */
-    scaleMin?: number;
-    /** Upper limit for scale clamping. */
-    scaleMax?: number;
-    /** Minimum on-screen pixel size for sprites (0 disables the lower clamp). */
-    spriteMinPixel?: number;
-    /** Maximum on-screen pixel size for sprites (0 disables the upper clamp). */
-    spriteMaxPixel?: 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;
 }
 /**
  * Allowed minification filters for sprite textures.
@@ -831,11 +814,11 @@ export interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
      */
     readonly getSpriteState: (spriteId: string) => SpriteCurrentState<TTag> | undefined;
     /**
-     * Enables or disables hit-test maintenance (quad-tree updates).
+     * Returns all sprite IDs currently managed by the layer.
      *
-     * @param {boolean} enabled - When false, hit testing is skipped and the internal data structure is cleared.
+     * @returns {string[]} Array of sprite identifiers.
      */
-    readonly setHitTestEnabled: (enabled: boolean) => void;
+    readonly getAllSpriteIds: () => string[];
     /**
      * Attaches an image definition to a sprite.
      *
@@ -902,6 +885,27 @@ export interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
      * @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.
      *

package/dist/utils/color.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 import { RgbaColor } from '../internalTypes';

package/dist/utils/image.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 import { SpriteImageRegisterOptions } from '../types';

package/dist/utils/looseQuadTree.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.18.0
+ * version: 0.19.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: ca8392c8aa3aae7e0e4e3c871e195d49b125e481
+ * git.commit.hash: 7bc93c11d7855dedb8d60f140af4e413252c32a7
  */
 
 export interface Rect {