maplibre-gl-layers 0.1.0 → 0.2.0

package/dist/interpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.1.0
+ * version: 0.2.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: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
  */
 
 import { EasingFunction, SpriteInterpolationMode, SpriteInterpolationOptions, SpriteLocation } from './types';

package/dist/location.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.1.0
+ * version: 0.2.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: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
  */
 
 import { SpriteLocation } from './types';

package/dist/math.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.1.0
+ * version: 0.2.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: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
  */
 
 import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpriteScalingOptions } from './types';
@@ -185,6 +185,18 @@ export declare const applySurfaceDisplacement: (baseLng: number, baseLat: number
  * @returns {[number, number]} Clip-space coordinates in the range [-1, 1].
  */
 export declare const screenToClip: (x: number, y: number, drawingBufferWidth: number, drawingBufferHeight: number, pixelRatio: number) => [number, number];
+/**
+ * Converts homogeneous clip coordinates back into screen-space pixels.
+ * @param {[number, number, number, number]} clipPosition - Homogeneous clip coordinates.
+ * @param {number} drawingBufferWidth - WebGL drawing buffer width in device pixels.
+ * @param {number} drawingBufferHeight - WebGL drawing buffer height in device pixels.
+ * @param {number} pixelRatio - Device pixel ratio relating CSS pixels to device pixels.
+ * @returns {{ x: number; y: number } | null} Screen-space coordinates or `null` when invalid.
+ */
+export declare const clipToScreen: (clipPosition: readonly [number, number, number, number], drawingBufferWidth: number, drawingBufferHeight: number, pixelRatio: number) => {
+    x: number;
+    y: number;
+} | null;
 /**
  * Index order used to decompose a quad into two triangles.
  * @constant
@@ -387,7 +399,13 @@ export declare const calculateBillboardCornerScreenPositions: (params: Billboard
  * @property {number} totalRotateDeg - Rotation applied to the sprite in degrees.
  * @property {SpriteAnchor} [anchor] - Anchor definition normalized between -1 and 1.
  * @property {SpriteImageOffset} [offset] - Offset definition applied in meters/deg.
- * @property {ProjectLngLatFn} project - Projection function mapping longitude/latitude to screen space.
+ * @property {ProjectLngLatFn} [project] - Projection function mapping longitude/latitude to screen space.
+ * @property {ProjectToClipSpaceFn} [projectToClipSpace] - Projection into clip space when available.
+ * @property {number} [drawingBufferWidth] - WebGL drawing buffer width in device pixels.
+ * @property {number} [drawingBufferHeight] - WebGL drawing buffer height in device pixels.
+ * @property {number} [pixelRatio] - Device pixel ratio relating CSS pixels to device pixels.
+ * @property {number} [altitudeMeters] - Altitude used when projecting points into clip space.
+ * @property {boolean} [resolveAnchorless] - When true, also computes the anchorless center.
  */
 export type SurfaceCenterParams = {
     baseLngLat: SpriteLocation;
@@ -399,7 +417,13 @@ export type SurfaceCenterParams = {
     totalRotateDeg: number;
     anchor?: SpriteAnchor;
     offset?: SpriteImageOffset;
-    project: ProjectLngLatFn;
+    project?: ProjectLngLatFn;
+    projectToClipSpace?: ProjectToClipSpaceFn;
+    drawingBufferWidth?: number;
+    drawingBufferHeight?: number;
+    pixelRatio?: number;
+    altitudeMeters?: number;
+    resolveAnchorless?: boolean;
 };
 /**
  * Output describing the resolved surface center and displacement details.
@@ -408,6 +432,9 @@ export type SurfaceCenterParams = {
  * @property {{ width: number; height: number }} worldDimensions - Sprite dimensions in world meters.
  * @property {{ east: number; north: number }} totalDisplacement - Combined anchor and offset displacement in meters.
  * @property {SpriteLocation} displacedLngLat - Geographic coordinates after applying displacement.
+ * @property {{ x: number; y: number } | null | undefined} [anchorlessCenter] - Anchorless screen coordinates when requested.
+ * @property {{ east: number; north: number } | undefined} [anchorlessDisplacement] - Offset-only displacement when requested.
+ * @property {SpriteLocation | undefined} [anchorlessLngLat] - Anchorless geographic coordinate when requested.
  */
 export type SurfaceCenterResult = {
     center: {
@@ -423,6 +450,15 @@ export type SurfaceCenterResult = {
         north: number;
     };
     displacedLngLat: SpriteLocation;
+    anchorlessCenter?: {
+        x: number;
+        y: number;
+    } | null;
+    anchorlessDisplacement?: {
+        east: number;
+        north: number;
+    };
+    anchorlessLngLat?: SpriteLocation;
 };
 /**
  * Calculates the projected center of a surface sprite and derives related world-space displacements.

package/dist/numericInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.1.0
+ * version: 0.2.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: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
  */
 
 import { EasingFunction, SpriteNumericInterpolationOptions } from './types';

package/dist/rotationInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.1.0
+ * version: 0.2.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: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
  */
 
 import { SpriteNumericInterpolationOptions } from './types';

package/dist/types.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.1.0
+ * version: 0.2.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: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
  */
 
 import { CustomLayerInterface } from 'maplibre-gl';
@@ -150,7 +150,8 @@ export interface SpriteImageDefinitionInitEntry extends SpriteImageDefinitionIni
 }
 /**
  * Parameters required to construct a new sprite.
- * @param TTag Tag type.
+ *
+ * @template TTag Tag type.
  */
 export interface SpriteInit<TTag> {
     /** Whether the sprite starts enabled. Defaults to true. */
@@ -162,26 +163,73 @@ export interface SpriteInit<TTag> {
     /** Optional tag value; null or omission means no tag. */
     tag?: TTag | null;
 }
-/** Sprite image state evaluated at runtime. */
+/**
+ * Entry for batch sprite creation, pairing a sprite identifier with its initial settings.
+ *
+ * @template TTag Tag type.
+ */
+export interface SpriteInitEntry<TTag> extends SpriteInit<TTag> {
+    /** Sprite identifier. */
+    spriteId: string;
+}
+/**
+ * Batch payload accepted by addSprites. Supports both record and array inputs.
+ *
+ * @template TTag Tag type.
+ */
+export type SpriteInitCollection<TTag> = Record<string, SpriteInit<TTag>> | readonly SpriteInitEntry<TTag>[];
+/**
+ * Sprite image state evaluated at runtime.
+ *
+ * @property {number} subLayer - Sub-layer index the image belongs to.
+ * @property {number} order - Ordering slot within the sub-layer.
+ * @property {string} imageId - Identifier of the registered image or glyph.
+ * @property {SpriteMode} mode - Rendering mode applied to the image.
+ * @property {number} opacity - Opacity multiplier applied when rendering.
+ * @property {number} scale - Scale factor converting pixels to meters.
+ * @property {Readonly<SpriteAnchor>} anchor - Anchor coordinates resolved for the image.
+ * @property {Readonly<SpriteImageOffset>} offset - Offset applied relative to the anchor point.
+ * @property {number} rotateDeg - Additional rotation in degrees.
+ * @property {boolean} autoRotation - Indicates whether auto-rotation is active.
+ * @property {number} autoRotationMinDistanceMeters - Minimum travel distance before auto-rotation updates.
+ * @property {number} resolvedBaseRotateDeg - Internal base rotation resolved for the current frame.
+ * @property {number} displayedRotateDeg - Rotation value actually used for rendering.
+ * @property {Readonly<SpriteImageOriginLocation> | undefined} originLocation - Optional reference to another image used for anchoring.
+ */
 export 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;
+    /** Opacity multiplier applied when rendering. */
     readonly opacity: number;
+    /** Scale factor converting pixels to meters. */
     readonly scale: number;
+    /** Anchor coordinates resolved for the image. */
     readonly anchor: Readonly<SpriteAnchor>;
+    /** Offset applied relative to the anchor point. */
     readonly offset: Readonly<SpriteImageOffset>;
+    /** Additional rotation in degrees. */
     readonly rotateDeg: 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;
+    /** Optional reference to another image used for anchoring. */
     readonly originLocation: Readonly<SpriteImageOriginLocation> | undefined;
 }
 /**
  * Current runtime state of a sprite.
- * @param TTag Tag type.
+ *
+ * @template TTag Tag type.
  */
 export interface SpriteCurrentState<TTag> {
     /** Sprite identifier. */
@@ -234,66 +282,169 @@ export interface SpriteImageRotationInterpolationOptions {
     /** Interpolation settings for offset.offsetDeg; null disables interpolation. */
     offsetDeg?: SpriteNumericInterpolationOptions | null;
 }
-/** Base structure for sprite updates. */
+/**
+ * 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 {TTag | null | undefined} tag - Optional tag value to replace the current one; `null` clears the tag.
+ */
 export 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;
 }
-/** Update entry describing a sprite image modification. */
+/**
+ * Update entry describing a sprite image modification.
+ *
+ * @property {number} subLayer - Target sub-layer that contains the image.
+ * @property {number} order - Order slot within the sub-layer.
+ * @property {SpriteImageDefinitionUpdate | null} image - Update payload, or `null` to remove the image.
+ */
 export 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;
 }
-/** Sprite update entry with optional image list. */
+/**
+ * Sprite update entry with optional image list.
+ *
+ * @template TTag Tag type stored on the sprite.
+ * @property {SpriteImageDefinitionUpdateEntry[] | undefined} images - Optional set of image updates.
+ */
 export interface SpriteUpdateEntry<TTag> extends SpriteUpdateEntryBase<TTag> {
+    /** Optional set of image updates. */
     images?: SpriteImageDefinitionUpdateEntry[];
 }
-/** Entry consumed by updateBulk to target a specific sprite. */
+/**
+ * Entry consumed by updateBulk to target a specific sprite.
+ *
+ * @template T Tag type stored on the sprite.
+ * @property {string} spriteId - Identifier of the sprite to update.
+ */
 export interface SpriteUpdateBulkEntry<T> extends SpriteUpdateEntry<T> {
+    /** Identifier of the sprite to update. */
     spriteId: string;
 }
-/** Callback-based helper for mutating sprite state. */
+/**
+ * Callback-based helper for mutating sprite state.
+ *
+ * @template TTag Tag type stored on the sprite.
+ * @property {() => ReadonlyMap<number, ReadonlySet<number>>} getImageIndexMap - Retrieves the current image layout.
+ * @property {(subLayer: number, order: number, imageInit: SpriteImageDefinitionInit) => boolean} addImage - Adds an image definition.
+ * @property {(subLayer: number, order: number, imageUpdate: SpriteImageDefinitionUpdate) => boolean} updateImage - Applies image updates.
+ * @property {(subLayer: number, order: number) => boolean} removeImage - Removes an image slot.
+ */
 export interface SpriteUpdaterEntry<TTag> extends SpriteUpdateEntryBase<TTag> {
+    /** Retrieves the current image layout. */
     readonly getImageIndexMap: () => ReadonlyMap<number, ReadonlySet<number>>;
+    /** Adds an image definition. */
     readonly addImage: (subLayer: number, order: number, imageInit: SpriteImageDefinitionInit) => boolean;
+    /** Applies image updates. */
     readonly updateImage: (subLayer: number, order: number, imageUpdate: SpriteImageDefinitionUpdate) => boolean;
+    /** Removes an image slot. */
     readonly removeImage: (subLayer: number, order: number) => boolean;
 }
-/** Represents a point in screen space. */
+/**
+ * Represents a point in screen space.
+ *
+ * @property {number} x - Horizontal screen coordinate in pixels.
+ * @property {number} y - Vertical screen coordinate in pixels.
+ */
 export interface SpriteScreenPoint {
+    /** Horizontal screen coordinate in pixels. */
     readonly x: number;
+    /** Vertical screen coordinate in pixels. */
     readonly y: number;
 }
-/** Event dispatched when a sprite is clicked or tapped. */
+/**
+ * Event dispatched when a sprite is clicked or tapped.
+ *
+ * @template T Tag type stored on sprites.
+ * @property {'spriteclick'} 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 | TouchEvent} originalEvent - Original DOM event.
+ */
 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;
+    /** Screen position of the interaction. */
     readonly screenPoint: SpriteScreenPoint;
+    /** Original DOM event. */
     readonly originalEvent: MouseEvent | PointerEvent | TouchEvent;
 }
-/** Map of events emitted by SpriteLayer. */
+/**
+ * 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.
+ */
 export interface SpriteLayerEventMap<T> {
+    /** Event fired when a sprite image is clicked. */
     readonly spriteclick: SpriteLayerClickEvent<T>;
 }
-/** Event listener callback. */
+/**
+ * Event listener callback.
+ *
+ * @template T Tag type stored on sprites.
+ * @template K Event key from {@link SpriteLayerEventMap}.
+ * @param {SpriteLayerEventMap<T>[K]} event - Event payload dispatched by SpriteLayer.
+ * @returns {void}
+ */
 export type SpriteLayerEventListener<T, K extends keyof SpriteLayerEventMap<T>> = (event: SpriteLayerEventMap<T>[K]) => void;
-/** Options controlling zoom-to-pixel scaling. */
+/**
+ * Options controlling zoom-to-pixel scaling.
+ *
+ * @property {number | undefined} metersPerPixel - Overrides the baseline meters-per-pixel ratio.
+ * @property {number | undefined} zoomMin - Minimum zoom level before scaling adjustments apply.
+ * @property {number | undefined} zoomMax - Maximum zoom level before scaling adjustments apply.
+ * @property {number | undefined} scaleMin - Lower limit for scale clamping.
+ * @property {number | undefined} scaleMax - Upper limit for scale clamping.
+ * @property {number | undefined} spriteMinPixel - Minimum on-screen pixel size for sprites.
+ * @property {number | undefined} spriteMaxPixel - Maximum on-screen pixel size for sprites.
+ */
 export interface SpriteScalingOptions {
+    /** Overrides the baseline meters-per-pixel ratio. */
     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. */
     spriteMinPixel?: number;
+    /** Maximum on-screen pixel size for sprites. */
     spriteMaxPixel?: number;
 }
-/** Options accepted when creating a SpriteLayer. */
+/**
+ * Options accepted when creating a SpriteLayer.
+ *
+ * @property {string | undefined} id - Optional layer identifier supplied to MapLibre.
+ * @property {SpriteScalingOptions | undefined} spriteScaling - Optional scaling controls.
+ */
 export interface SpriteLayerOptions {
+    /** Optional layer identifier supplied to MapLibre. */
     id?: string;
+    /** Optional scaling controls. */
     spriteScaling?: SpriteScalingOptions;
 }
 /** Horizontal alignment options for text glyphs. */
@@ -313,39 +464,209 @@ export type SpriteTextGlyphDimensions = {
     readonly maxWidthPixel: number;
     readonly lineHeightPixel?: never;
 };
+/**
+ * Text glyph appearance options.
+ *
+ * @property {string | undefined} fontFamily - Font family name.
+ * @property {number | undefined} fontSizePixel - Font size in pixels.
+ * @property {string | undefined} fontWeight - CSS font-weight value.
+ * @property {'normal' | 'italic' | undefined} fontStyle - CSS font-style value.
+ * @property {string | undefined} color - Text fill color.
+ * @property {number | undefined} letterSpacingPixel - Letter spacing in pixels.
+ * @property {string | undefined} backgroundColor - Background color applied behind the text.
+ * @property {SpriteTextGlyphPaddingPixel | undefined} paddingPixel - Padding around the glyph.
+ * @property {string | undefined} borderColor - Outline color.
+ * @property {number | undefined} borderWidthPixel - Outline width in pixels.
+ * @property {number | undefined} borderRadiusPixel - Border radius in pixels.
+ * @property {SpriteTextGlyphHorizontalAlign | undefined} textAlign - Horizontal alignment of multiline text.
+ * @property {number | undefined} renderPixelRatio - Pixel ratio used when rendering the glyph.
+ */
 export interface SpriteTextGlyphOptions {
+    /** Font family name. */
     fontFamily?: string;
+    /** Font size in pixels. */
     fontSizePixel?: number;
+    /** 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 radius in pixels. */
     borderRadiusPixel?: number;
+    /** Horizontal alignment of multiline text. */
     textAlign?: SpriteTextGlyphHorizontalAlign;
+    /** Pixel ratio used when rendering the glyph. */
     renderPixelRatio?: number;
 }
 /**
  * MapLibre layer interface for SpriteLayer.
  * Renders large numbers of sprites and supports high-frequency updates.
- * @param T Sprite tag type.
+ *
+ * @template TTag Sprite tag type.
  */
-export interface SpriteLayerInterface<T = any> extends CustomLayerInterface {
+export 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.
+     * @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>;
+    /**
+     * 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;
-    readonly addSprite: (spriteId: string, init: SpriteInit<T>) => 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;
-    readonly getSpriteState: (spriteId: string) => SpriteCurrentState<T> | undefined;
+    /**
+     * 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;
+    /**
+     * 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;
-    readonly updateSprite: (spriteId: string, update: SpriteUpdateEntry<T>) => boolean;
-    readonly updateBulk: (updateBulkList: SpriteUpdateBulkEntry<T>[]) => number;
-    readonly updateForEach: (updater: (sprite: SpriteCurrentState<T>, update: SpriteUpdaterEntry<T>) => boolean) => number;
-    readonly on: <K extends keyof SpriteLayerEventMap<T>>(type: K, listener: SpriteLayerEventListener<T, K>) => void;
-    readonly off: <K extends keyof SpriteLayerEventMap<T>>(type: K, listener: SpriteLayerEventListener<T, K>) => void;
+    /**
+     * 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;
+    /**
+     * Applies a batch of sprite updates.
+     *
+     * @param {SpriteUpdateBulkEntry<TTag>[]} updateBulkList - List of sprite updates.
+     * @returns {number} Number of sprites that were updated.
+     */
+    readonly updateBulk: (updateBulkList: SpriteUpdateBulkEntry<TTag>[]) => 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;
+    /**
+     * 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;
 }

package/dist/utils.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.1.0
+ * version: 0.2.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: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
  */
 
 /**