maplibre-gl-layers 0.5.0 → 0.10.0

package/dist/internalTypes.d.ts

@@ -0,0 +1,189 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.10.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: 58b99588e56fc80c6874d78a17e91a50901abc17
+ */
+
+import { SpriteMode, SpriteAnchor, SpriteImageOffset, SpriteInterpolationOptions, SpriteImageOriginLocation, SpriteLocation, SpriteTextGlyphHorizontalAlign, SpriteTextureMagFilter, SpriteTextureMinFilter, SpriteInterpolationMode, EasingFunction } from './types';
+/**
+ * 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.
+ *
+ * @property mode - Strategy used to resolve the target location (feedback or feedforward).
+ * @property durationMs - Total time allocated for the interpolation in milliseconds.
+ * @property easing - Resolved easing function applied to raw progress values.
+ * @property startTimestamp - Epoch millisecond when the interpolation started, or -1 when uninitialized.
+ * @property from - Origin sprite location cloned from the current render state.
+ * @property to - Destination sprite location being interpolated towards.
+ */
+export interface SpriteInterpolationState {
+    readonly mode: SpriteInterpolationMode;
+    readonly durationMs: number;
+    readonly easing: EasingFunction;
+    startTimestamp: number;
+    readonly from: SpriteLocation;
+    readonly to: SpriteLocation;
+}
+/**
+ * Runtime state tracked for numeric interpolations.
+ * @property {number} durationMs - Total duration of the interpolation in milliseconds.
+ * @property {EasingFunction} easing - Easing function applied to progress samples.
+ * @property {number} from - Start value used for interpolation.
+ * @property {number} to - Adjusted target along the shortest rotation path.
+ * @property {number} finalValue - Caller-requested final value (used once interpolation completes).
+ * @property {number} startTimestamp - Timestamp when interpolation began, `-1` until evaluation starts.
+ */
+export interface DegreeInterpolationState {
+    readonly durationMs: number;
+    readonly easing: EasingFunction;
+    readonly from: number;
+    readonly to: number;
+    readonly finalValue: number;
+    startTimestamp: number;
+}
+export interface DistanceInterpolationState {
+    readonly durationMs: number;
+    readonly easing: EasingFunction;
+    readonly from: number;
+    readonly to: number;
+    readonly finalValue: number;
+    startTimestamp: number;
+}
+/**
+ * Alias for the interpolation state used internally by sprites.
+ */
+export type InternalSpriteInterpolationState = SpriteInterpolationState;
+/**
+ * Texture filtering parameters resolved from the public options structure.
+ */
+export interface ResolvedTextureFilteringOptions {
+    readonly minFilter: SpriteTextureMinFilter;
+    readonly magFilter: SpriteTextureMagFilter;
+    readonly generateMipmaps: boolean;
+    readonly maxAnisotropy: number;
+}
+/**
+ * Image metadata ready for use as a WebGL texture.
+ */
+export interface RegisteredImage {
+    id: string;
+    width: number;
+    height: number;
+    bitmap: ImageBitmap;
+    texture: WebGLTexture | undefined;
+}
+/**
+ * Padding resolved for glyph rendering with guaranteed non-negative values.
+ */
+export interface ResolvedTextGlyphPadding {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+/**
+ * Border sides resolved for glyph rendering.
+ */
+export interface ResolvedBorderSides {
+    readonly top: boolean;
+    readonly right: boolean;
+    readonly bottom: boolean;
+    readonly left: boolean;
+}
+/**
+ * Fully resolved glyph rendering options with defaults applied.
+ */
+export interface ResolvedTextGlyphOptions {
+    readonly fontFamily: string;
+    readonly fontStyle: 'normal' | 'italic';
+    readonly fontWeight: string;
+    readonly fontSizePixel: number;
+    readonly color: string;
+    readonly letterSpacingPixel: number;
+    readonly backgroundColor?: string;
+    readonly paddingPixel: ResolvedTextGlyphPadding;
+    readonly borderColor?: string;
+    readonly borderWidthPixel: number;
+    readonly borderRadiusPixel: number;
+    readonly borderSides: ResolvedBorderSides;
+    readonly textAlign: SpriteTextGlyphHorizontalAlign;
+    readonly renderPixelRatio: number;
+}
+/**
+ * Mutable point reused when computing hit-test corners.
+ */
+export interface MutableSpriteScreenPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Compact representation of an Array-like 4x4 matrix.
+ */
+export type MatrixInput = ArrayLike<number>;
+/**
+ * Cached clip-space context containing the mercator matrix required to project coordinates.
+ */
+export type ClipContext = {
+    readonly mercatorMatrix: MatrixInput;
+};
+/**
+ * 2D canvas rendering context accepted by the glyph renderer.
+ */
+export type Canvas2DContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/**
+ * Canvas sources supported when rendering text glyphs.
+ */
+export type Canvas2DSource = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * Base attributes for an image that composes a sprite.
+ */
+export interface InternalSpriteImageState {
+    subLayer: number;
+    order: number;
+    imageId: string;
+    mode: SpriteMode;
+    opacity: number;
+    scale: number;
+    anchor: SpriteAnchor;
+    offset: SpriteImageOffset;
+    rotateDeg: number;
+    displayedRotateDeg: number;
+    autoRotation: boolean;
+    autoRotationMinDistanceMeters: number;
+    resolvedBaseRotateDeg: number;
+    originLocation?: SpriteImageOriginLocation;
+    rotationInterpolationState: DegreeInterpolationState | null;
+    rotationInterpolationOptions: SpriteInterpolationOptions | null;
+    offsetDegInterpolationState: DegreeInterpolationState | null;
+    offsetMetersInterpolationState: DistanceInterpolationState | null;
+    lastCommandRotateDeg: number;
+    lastCommandOffsetDeg: number;
+    lastCommandOffsetMeters: number;
+    hitTestCorners?: [
+        MutableSpriteScreenPoint,
+        MutableSpriteScreenPoint,
+        MutableSpriteScreenPoint,
+        MutableSpriteScreenPoint
+    ];
+}
+/**
+ * Current sprite state tracked internally by the layer.
+ */
+export interface InternalSpriteCurrentState<TTag> {
+    spriteId: string;
+    isEnabled: boolean;
+    currentLocation: SpriteLocation;
+    fromLocation?: SpriteLocation;
+    toLocation?: SpriteLocation;
+    images: Map<number, Map<number, InternalSpriteImageState>>;
+    tag: TTag | null;
+    interpolationState: InternalSpriteInterpolationState | null;
+    pendingInterpolationOptions: SpriteInterpolationOptions | null;
+    lastCommandLocation: SpriteLocation;
+    lastAutoRotationLocation: SpriteLocation;
+    lastAutoRotationAngleDeg: number;
+}

package/dist/interpolation.d.ts

@@ -1,33 +1,15 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.5.0
+ * version: 0.10.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: ce37eea48b788c36b4bf98cdfce83b95a85833ee
+ * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
  */
 
-import { EasingFunction, SpriteInterpolationMode, SpriteInterpolationOptions, SpriteLocation } from './types';
-/**
- * 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.
- *
- * @property mode - Strategy used to resolve the target location (feedback or feedforward).
- * @property durationMs - Total time allocated for the interpolation in milliseconds.
- * @property easing - Resolved easing function applied to raw progress values.
- * @property startTimestamp - Epoch millisecond when the interpolation started, or -1 when uninitialised.
- * @property from - Origin sprite location cloned from the current render state.
- * @property to - Destination sprite location being interpolated towards.
- */
-export interface SpriteInterpolationState {
-    readonly mode: SpriteInterpolationMode;
-    readonly durationMs: number;
-    readonly easing: EasingFunction;
-    startTimestamp: number;
-    readonly from: SpriteLocation;
-    readonly to: SpriteLocation;
-}
+import { SpriteInterpolationOptions, SpriteLocation } from './types';
+import { SpriteInterpolationState } from './internalTypes';
 /**
  * Parameters required to create a fresh interpolation state for the next animation segment.
  *

package/dist/interpolationChannels.d.ts

@@ -0,0 +1,37 @@
+/*!
+ * name: maplibre-gl-layers
+ * version: 0.10.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: 58b99588e56fc80c6874d78a17e91a50901abc17
+ */
+
+import { SpriteInterpolationOptions, SpriteImageOffset } from './types';
+import { InternalSpriteImageState } from './internalTypes';
+/**
+ * Ensures the rotation channel reflects the latest targets, optionally overriding interpolation.
+ */
+export declare const syncImageRotationChannel: (image: InternalSpriteImageState, optionsOverride?: SpriteInterpolationOptions | null) => void;
+/**
+ * Clears any running offset angle interpolation.
+ */
+export declare const clearOffsetDegInterpolation: (image: InternalSpriteImageState) => void;
+/**
+ * Clears any running offset distance interpolation in meters.
+ */
+export declare const clearOffsetMetersInterpolation: (image: InternalSpriteImageState) => void;
+/**
+ * Executes all interpolation steppers for an image and reports whether any remain active.
+ */
+export declare const stepSpriteImageInterpolations: (image: InternalSpriteImageState, timestamp: number) => boolean;
+interface ApplyOffsetUpdateOptions {
+    readonly deg?: SpriteInterpolationOptions | null;
+    readonly meters?: SpriteInterpolationOptions | null;
+}
+/**
+ * Applies offset updates across both angular and radial channels.
+ */
+export declare const applyOffsetUpdate: (image: InternalSpriteImageState, nextOffset: SpriteImageOffset, options?: ApplyOffsetUpdateOptions) => void;
+export {};

package/dist/location.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.5.0
+ * version: 0.10.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: ce37eea48b788c36b4bf98cdfce83b95a85833ee
+ * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
  */
 
 import { SpriteLocation } from './types';

package/dist/math.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.5.0
+ * version: 0.10.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: ce37eea48b788c36b4bf98cdfce83b95a85833ee
+ * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
  */
 
 import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpriteScalingOptions } from './types';

package/dist/rotationInterpolation.d.ts

@@ -1,40 +1,42 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.5.0
+ * version: 0.10.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: ce37eea48b788c36b4bf98cdfce83b95a85833ee
+ * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
  */
 
-import { SpriteNumericInterpolationOptions } from './types';
-import { NumericInterpolationState } from './numericInterpolation';
+import { SpriteInterpolationOptions } from './types';
+import { DegreeInterpolationState } from './internalTypes';
 /**
  * Normalizes an absolute angle in degrees to the range [0, 360).
  * @param {number} angle - Angle provided by the caller which may fall outside a single revolution.
  * @returns {number} Angle wrapped to [0, 360) with negative zero converted to zero.
  */
-export declare const normaliseAngleDeg: (angle: number) => number;
+export declare const normalizeAngleDeg: (angle: number) => number;
 /**
  * Parameters describing the rotation update request.
  * @property {number} currentAngleDeg - Current angle already applied to the sprite in degrees.
  * @property {number} targetAngleDeg - Desired angle in degrees that should be reached.
- * @property {SpriteNumericInterpolationOptions | null} [options] - Optional interpolation configuration.
+ * @property {number | undefined} previousCommandAngleDeg - Previous commanded angle for feed-forward prediction.
+ * @property {SpriteInterpolationOptions | null} [options] - Optional interpolation configuration.
  */
 export interface ResolveRotationTargetParams {
     currentAngleDeg: number;
     targetAngleDeg: number;
-    options?: SpriteNumericInterpolationOptions | null;
+    previousCommandAngleDeg?: number;
+    options?: SpriteInterpolationOptions | null;
 }
 /**
  * Result produced by {@link resolveRotationTarget} when determining the next rotation step.
  * @property {number} nextAngleDeg - Angle that should be applied immediately.
- * @property {NumericInterpolationState | null} interpolationState - Optional state for animating toward the target.
+ * @property {DegreeInterpolationState | null} interpolationState - Optional state for animating toward the target.
  */
 export interface ResolveRotationTargetResult {
     readonly nextAngleDeg: number;
-    readonly interpolationState: NumericInterpolationState | null;
+    readonly interpolationState: DegreeInterpolationState | null;
 }
 /**
  * Determines whether a rotation change requires interpolation and, if so, produces the state to drive it.

package/dist/types.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.5.0
+ * version: 0.10.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: ce37eea48b788c36b4bf98cdfce83b95a85833ee
+ * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
  */
 
 import { CustomLayerInterface } from 'maplibre-gl';
@@ -71,6 +71,28 @@ export interface SpriteImageOriginLocation {
      */
     useResolvedAnchor?: boolean;
 }
+/** Defines movement interpolation modes. */
+export type SpriteInterpolationMode = 'feedback' | 'feedforward';
+/** Easing function signature used to map interpolation progress. */
+export type EasingFunction = (progress: number) => number;
+/** Options for interpolating values. */
+export interface SpriteInterpolationOptions {
+    /** Interpolation mode; defaults to feedback. */
+    mode?: SpriteInterpolationMode;
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** Easing function mapping interpolation progress. Defaults to linear. */
+    easing?: EasingFunction;
+}
+/** Interpolation configuration for rotateDeg and offsetDeg. */
+export interface SpriteImageInterpolationOptions {
+    /** Interpolation settings for rotateDeg; null disables interpolation. */
+    rotateDeg?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for offset.offsetDeg; null disables interpolation. */
+    offsetDeg?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for offset.offsetMeters; null disables interpolation. */
+    offsetMeters?: SpriteInterpolationOptions | null;
+}
 /**
  * Initial attributes that define a sprite image.
  */
@@ -108,9 +130,9 @@ export interface SpriteImageDefinitionInit {
      */
     autoRotationMinDistanceMeters?: number;
     /**
-     * Optional interpolation settings for rotateDeg and offsetDeg.
+     * Optional interpolation settings.
      */
-    rotationInterpolation?: SpriteImageRotationInterpolationOptions;
+    interpolation?: SpriteImageInterpolationOptions;
 }
 /**
  * Update payload for a sprite image. Properties left undefined are ignored.
@@ -134,8 +156,8 @@ export interface SpriteImageDefinitionUpdate {
     autoRotation?: boolean;
     /** Minimum distance in meters before auto-rotation updates. */
     autoRotationMinDistanceMeters?: number;
-    /** Optional interpolation settings applied to rotateDeg and offsetDeg. */
-    rotationInterpolation?: SpriteImageRotationInterpolationOptions;
+    /** Optional interpolation settings. */
+    interpolation?: SpriteImageInterpolationOptions;
 }
 /**
  * Helper for bulk initializing sprite images.
@@ -255,40 +277,13 @@ export interface SpriteCurrentState<TTag> {
     /** Optional tag value; null indicates no tag. */
     readonly tag: TTag | null;
 }
-/** Defines movement interpolation modes. */
-export type SpriteInterpolationMode = 'feedback' | 'feedforward';
-/** Easing function signature used to map interpolation progress. */
-export type EasingFunction = (progress: number) => number;
-/** Options controlling position interpolation. */
-export interface SpriteInterpolationOptions {
-    /** Interpolation mode; defaults to feedback. */
-    mode?: SpriteInterpolationMode;
-    /** Duration in milliseconds. */
-    durationMs: number;
-    /** Easing function mapping interpolation progress. Defaults to linear. */
-    easing?: EasingFunction;
-}
-/** Options for interpolating numeric values such as angles. */
-export interface SpriteNumericInterpolationOptions {
-    /** Duration in milliseconds. */
-    durationMs: number;
-    /** Easing function mapping interpolation progress. Defaults to linear. */
-    easing?: EasingFunction;
-}
-/** Interpolation configuration for rotateDeg and offsetDeg. */
-export interface SpriteImageRotationInterpolationOptions {
-    /** Interpolation settings for rotateDeg; null disables interpolation. */
-    rotateDeg?: SpriteNumericInterpolationOptions | null;
-    /** Interpolation settings for offset.offsetDeg; null disables interpolation. */
-    offsetDeg?: SpriteNumericInterpolationOptions | null;
-}
 /**
  * Base structure for sprite updates.
  *
  * @template TTag Tag type stored on the sprite.
  * @property {boolean | undefined} isEnabled - Optional toggle to enable or disable the sprite.
  * @property {SpriteLocation | undefined} location - Optional target location for the sprite.
- * @property {SpriteInterpolationOptions | null | undefined} interpolation - Optional interpolation settings; `null` disables interpolation.
+ * @property {SpriteLocationInterpolationOptions | null | undefined} interpolation - Optional location interpolation settings; `null` disables interpolation.
  * @property {TTag | null | undefined} tag - Optional tag value to replace the current one; `null` clears the tag.
  */
 export interface SpriteUpdateEntryBase<TTag> {
@@ -326,11 +321,6 @@ export interface SpriteUpdateEntry<TTag> extends SpriteUpdateEntryBase<TTag> {
     /** Optional set of image updates. */
     images?: SpriteImageDefinitionUpdateEntry[];
 }
-/** @deprecated Scheduled for removal in a future release. Use {@link SpriteLayerInterface.mutateSprites} instead. */
-export interface SpriteUpdateBulkEntry<T> extends SpriteUpdateEntry<T> {
-    /** @deprecated Scheduled for removal in a future release. Use {@link SpriteLayerInterface.mutateSprites} instead. */
-    spriteId: string;
-}
 /**
  * Callback-based helper for mutating sprite state.
  *
@@ -374,7 +364,7 @@ export interface SpriteMutateCallbacks<TTag, TSourceItem extends SpriteMutateSou
      * (or `null`) to skip creation.
      *
      * @param sourceItem Source item that produced the sprite ID.
-     * @returns Sprite initialiser to insert, or `undefined`/`null` to skip.
+     * @returns Sprite initializer to insert, or `undefined`/`null` to skip.
      */
     add: (sourceItem: TSourceItem) => SpriteInit<TTag> | null | undefined;
     /**
@@ -413,24 +403,49 @@ export interface SpriteScreenPoint {
 export interface SpriteLayerClickEvent<T> {
     /** Discriminated event type. */
     readonly type: 'spriteclick';
-    /** Snapshot of the sprite that was hit. */
-    readonly sprite: SpriteCurrentState<T>;
-    /** Sprite image that received the interaction. */
-    readonly image: SpriteImageState;
+    /** Snapshot of the sprite that was hit, or `undefined` when it no longer exists. */
+    readonly sprite: SpriteCurrentState<T> | 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 dispatched when a sprite is hovered by a pointing device.
+ *
+ * @template T Tag type stored on sprites.
+ * @property {'spritehover'} type - Discriminated event type.
+ * @property {SpriteCurrentState<T>} sprite - Snapshot of the sprite that was hit.
+ * @property {SpriteImageState} image - Sprite image that received the interaction.
+ * @property {SpriteScreenPoint} screenPoint - Screen position of the interaction.
+ * @property {MouseEvent | PointerEvent} originalEvent - Original hover-capable DOM event.
+ */
+export interface SpriteLayerHoverEvent<T> {
+    /** Discriminated event type. */
+    readonly type: 'spritehover';
+    /** Snapshot of the sprite that was hit, or `undefined` when it no longer exists. */
+    readonly sprite: SpriteCurrentState<T> | 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;
+}
 /**
  * Map of events emitted by SpriteLayer.
  *
  * @template T Tag type stored on sprites.
  * @property {SpriteLayerClickEvent<T>} spriteclick - Event fired when a sprite image is clicked.
+ * @property {SpriteLayerHoverEvent<T>} spritehover - Event fired when a sprite image is hovered.
  */
 export interface SpriteLayerEventMap<T> {
     /** Event fired when a sprite image is clicked. */
     readonly spriteclick: SpriteLayerClickEvent<T>;
+    /** Event fired when a sprite image is hovered. */
+    readonly spritehover: SpriteLayerHoverEvent<T>;
 }
 /**
  * Event listener callback.
@@ -472,26 +487,68 @@ export interface SpriteScalingOptions {
     spriteMaxPixel?: number;
 }
 /**
- * Unlimited (default) values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
- * metersPerPixel is 1.
+ * Allowed minification filters for sprite textures.
+ */
+export type SpriteTextureMinFilter = 'nearest' | 'linear' | 'nearest-mipmap-nearest' | 'nearest-mipmap-linear' | 'linear-mipmap-nearest' | 'linear-mipmap-linear';
+/**
+ * Allowed magnification filters for sprite textures.
  */
-export declare const UNLIMITED_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+export type SpriteTextureMagFilter = 'nearest' | 'linear';
 /**
- * Standard values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
- * metersPerPixel is 1.
+ * Texture filtering configuration.
+ *
+ * @property {SpriteTextureMinFilter | undefined} minFilter - Minification filter to apply (defaults to `linear`).
+ * @property {SpriteTextureMagFilter | undefined} magFilter - Magnification filter to apply (defaults to `linear`).
+ * @property {boolean | undefined} generateMipmaps - Generates mipmaps during upload when true (defaults to `false`).
+ * @property {number | undefined} maxAnisotropy - Desired anisotropy factor (>= 1) when EXT_texture_filter_anisotropic is available.
  */
-export declare const STANDARD_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+export interface SpriteTextureFilteringOptions {
+    minFilter?: SpriteTextureMinFilter;
+    magFilter?: SpriteTextureMagFilter;
+    generateMipmaps?: boolean;
+    maxAnisotropy?: number;
+}
 /**
  * Options accepted when creating a SpriteLayer.
  *
  * @property {string | undefined} id - Optional layer identifier supplied to MapLibre.
  * @property {SpriteScalingOptions | undefined} spriteScaling - Optional scaling controls. Default is UNLIMITED_SPRITE_SCALING_OPTIONS.
+ * @property {SpriteTextureFilteringOptions | undefined} textureFiltering - Optional texture filtering overrides.
  */
 export interface SpriteLayerOptions {
     /** Optional layer identifier supplied to MapLibre. */
     id?: string;
     /** Optional scaling controls. */
     spriteScaling?: SpriteScalingOptions;
+    /** Optional texture filtering configuration. */
+    textureFiltering?: SpriteTextureFilteringOptions;
+}
+/**
+ * Options used when registering SVG images.
+ */
+export 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;
+}
+/**
+ * Options accepted by {@link SpriteLayerInterface.registerImage}.
+ */
+export 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;
 }
 /** Horizontal alignment options for text glyphs. */
 export type SpriteTextGlyphHorizontalAlign = 'left' | 'center' | 'right';
@@ -572,9 +629,10 @@ export interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
      *
      * @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) => Promise<boolean>;
+    readonly registerImage: (imageId: string, image: string | ImageBitmap, options?: SpriteImageRegisterOptions) => Promise<boolean>;
     /**
      * Registers a text glyph texture for later use.
      *
@@ -690,17 +748,13 @@ export interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
      * @returns {boolean} `true` when the sprite was found and updated.
      */
     readonly updateSprite: (spriteId: string, update: SpriteUpdateEntry<TTag>) => boolean;
-    /**
-     * @deprecated Use {@link SpriteLayerInterface.mutateSprites} instead for clearer mutation flows.
-     */
-    readonly updateBulk: (updateBulkList: SpriteUpdateBulkEntry<TTag>[]) => number;
     /**
      * 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
-     * initialiser and each `modify` that either invoked the updater helper or returned `'remove'`.
+     * 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;
     /**

package/dist/utils.d.ts

@@ -1,16 +1,32 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.5.0
+ * version: 0.10.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: ce37eea48b788c36b4bf98cdfce83b95a85833ee
+ * git.commit.hash: 58b99588e56fc80c6874d78a17e91a50901abc17
  */
 
+import { SpriteImageRegisterOptions } from './types';
+export type SvgSizeResolutionErrorCode = 'size-missing' | 'viewbox-disabled' | 'invalid-dimensions';
+export declare class SvgSizeResolutionError extends Error implements Error {
+    readonly code: SvgSizeResolutionErrorCode;
+    constructor(message: string, code: SvgSizeResolutionErrorCode);
+}
+/**
+ * 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>;
 /**
  * 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) => Promise<ImageBitmap>;
+export declare const loadImageBitmap: (url: string, options?: SpriteImageRegisterOptions) => Promise<ImageBitmap>;