@accelint/map-toolkit 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @accelint/map-toolkit
 
+## 1.3.0
+
+### Minor Changes
+
+- 58199e5: Updates use-cursor-coordinates to format MGRS and UTM default coordinates to follow a more expected format.
+
+### Patch Changes
+
+- 03c1e39: Add a tweak for the Viewport Resize debounce timing, 500 -> 200, for better visual feedback on updates.
+- 0265877: Fixed error handling in `useCursorCoordinates` hook for coordinates outside UTM/MGRS valid range. UTM and MGRS coordinate systems are only valid between 80°S and 84°N. The hook now returns the default placeholder (`--, --`) when attempting to format polar coordinates in these formats.
+
 ## 1.2.0
 
 ### Minor Changes

package/catalog-info.yaml

@@ -12,14 +12,14 @@ metadata:
     Dependencies:
 
     accelint_biome-config@1.1.0, accelint_bus@3.0.2, accelint_core@0.5.2,
-    accelint_design-foundation@2.1.0, accelint_design-toolkit@9.3.0,
+    accelint_design-foundation@2.1.0, accelint_design-toolkit@9.5.0,
     accelint_geo@0.5.1, accelint_logger@0.1.5,
-    accelint_postcss-tailwind-css-modules@1.0.1, accelint_smeegl@0.3.4,
+    accelint_postcss-tailwind-css-modules@1.0.1, accelint_smeegl@0.3.5,
     accelint_typescript-config@0.1.4, accelint_vitest-config@0.1.6
   annotations:
     backstage.io/edit-url: https://github.com/gohypergiant/standard-toolkit/blob/main/packages/map-toolkit/catalog-info.yaml
     backstage.io/techdocs-ref: dir:.
-    package/version: 1.2.0
+    package/version: 1.3.0
     github.com/project-slug: gohypergiant/standard-toolkit
   links:
     - url: https://github.com/gohypergiant/standard-toolkit/tree/main/packages/map-toolkit

package/dist/camera/events.d.ts

@@ -1,5 +1,50 @@
 //#region src/camera/events.d.ts
+/**
+ * Namespace prefix for all camera-related events.
+ *
+ * @example
+ * ```typescript
+ * import { CameraEventNamespace } from '@accelint/map-toolkit/camera';
+ *
+ * const customEvent = `${CameraEventNamespace}:customAction`;
+ * // Result: 'camera:customAction'
+ * ```
+ */
 declare const CameraEventNamespace = "camera";
+/**
+ * Event type constants for camera operations.
+ *
+ * Use these constants with the broadcast bus to control camera behavior across
+ * your application. Each event type corresponds to a specific camera operation.
+ *
+ * @example
+ * ```typescript
+ * import { Broadcast } from '@accelint/bus';
+ * import { CameraEventTypes } from '@accelint/map-toolkit/camera';
+ * import type { CameraEvent } from '@accelint/map-toolkit/camera';
+ *
+ * const bus = Broadcast.getInstance<CameraEvent>();
+ *
+ * // Set camera center
+ * bus.emit(CameraEventTypes.setCenter, {
+ *   id: 'map-1',
+ *   latitude: 37.7749,
+ *   longitude: -122.4194,
+ *   zoom: 10,
+ * });
+ *
+ * // Change view mode
+ * bus.emit(CameraEventTypes.setView, {
+ *   id: 'map-1',
+ *   view: '2.5D',
+ * });
+ *
+ * // Reset camera to initial state
+ * bus.emit(CameraEventTypes.reset, {
+ *   id: 'map-1',
+ * });
+ * ```
+ */
 declare const CameraEventTypes: {
   readonly setView: "camera:setView";
   readonly setProjection: "camera:setProjection";

package/dist/camera/events.js

@@ -12,7 +12,52 @@
 
 
 //#region src/camera/events.ts
+/**
+* Namespace prefix for all camera-related events.
+*
+* @example
+* ```typescript
+* import { CameraEventNamespace } from '@accelint/map-toolkit/camera';
+*
+* const customEvent = `${CameraEventNamespace}:customAction`;
+* // Result: 'camera:customAction'
+* ```
+*/
 const CameraEventNamespace = "camera";
+/**
+* Event type constants for camera operations.
+*
+* Use these constants with the broadcast bus to control camera behavior across
+* your application. Each event type corresponds to a specific camera operation.
+*
+* @example
+* ```typescript
+* import { Broadcast } from '@accelint/bus';
+* import { CameraEventTypes } from '@accelint/map-toolkit/camera';
+* import type { CameraEvent } from '@accelint/map-toolkit/camera';
+*
+* const bus = Broadcast.getInstance<CameraEvent>();
+*
+* // Set camera center
+* bus.emit(CameraEventTypes.setCenter, {
+*   id: 'map-1',
+*   latitude: 37.7749,
+*   longitude: -122.4194,
+*   zoom: 10,
+* });
+*
+* // Change view mode
+* bus.emit(CameraEventTypes.setView, {
+*   id: 'map-1',
+*   view: '2.5D',
+* });
+*
+* // Reset camera to initial state
+* bus.emit(CameraEventTypes.reset, {
+*   id: 'map-1',
+* });
+* ```
+*/
 const CameraEventTypes = {
 	setView: `${CameraEventNamespace}:setView`,
 	setProjection: `${CameraEventNamespace}:setProjection`,

package/dist/camera/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","names":[],"sources":["../../src/camera/events.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const CameraEventNamespace = 'camera';\n\nexport const CameraEventTypes = {\n  setView: `${CameraEventNamespace}:setView`,\n  setProjection: `${CameraEventNamespace}:setProjection`,\n  setZoom: `${CameraEventNamespace}:setZoom`,\n  setRotation: `${CameraEventNamespace}:setRotation`,\n  setPitch: `${CameraEventNamespace}:setPitch`,\n  setCenter: `${CameraEventNamespace}:setCenter`,\n  fitBounds: `${CameraEventNamespace}:fitBounds`,\n  reset: `${CameraEventNamespace}:reset`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,uBAAuB;AAEpC,MAAa,mBAAmB;CAC9B,SAAS,GAAG,qBAAqB;CACjC,eAAe,GAAG,qBAAqB;CACvC,SAAS,GAAG,qBAAqB;CACjC,aAAa,GAAG,qBAAqB;CACrC,UAAU,GAAG,qBAAqB;CAClC,WAAW,GAAG,qBAAqB;CACnC,WAAW,GAAG,qBAAqB;CACnC,OAAO,GAAG,qBAAqB;CAChC"}
+{"version":3,"file":"events.js","names":[],"sources":["../../src/camera/events.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Namespace prefix for all camera-related events.\n *\n * @example\n * ```typescript\n * import { CameraEventNamespace } from '@accelint/map-toolkit/camera';\n *\n * const customEvent = `${CameraEventNamespace}:customAction`;\n * // Result: 'camera:customAction'\n * ```\n */\nexport const CameraEventNamespace = 'camera';\n\n/**\n * Event type constants for camera operations.\n *\n * Use these constants with the broadcast bus to control camera behavior across\n * your application. Each event type corresponds to a specific camera operation.\n *\n * @example\n * ```typescript\n * import { Broadcast } from '@accelint/bus';\n * import { CameraEventTypes } from '@accelint/map-toolkit/camera';\n * import type { CameraEvent } from '@accelint/map-toolkit/camera';\n *\n * const bus = Broadcast.getInstance<CameraEvent>();\n *\n * // Set camera center\n * bus.emit(CameraEventTypes.setCenter, {\n *   id: 'map-1',\n *   latitude: 37.7749,\n *   longitude: -122.4194,\n *   zoom: 10,\n * });\n *\n * // Change view mode\n * bus.emit(CameraEventTypes.setView, {\n *   id: 'map-1',\n *   view: '2.5D',\n * });\n *\n * // Reset camera to initial state\n * bus.emit(CameraEventTypes.reset, {\n *   id: 'map-1',\n * });\n * ```\n */\nexport const CameraEventTypes = {\n  setView: `${CameraEventNamespace}:setView`,\n  setProjection: `${CameraEventNamespace}:setProjection`,\n  setZoom: `${CameraEventNamespace}:setZoom`,\n  setRotation: `${CameraEventNamespace}:setRotation`,\n  setPitch: `${CameraEventNamespace}:setPitch`,\n  setCenter: `${CameraEventNamespace}:setCenter`,\n  fitBounds: `${CameraEventNamespace}:fitBounds`,\n  reset: `${CameraEventNamespace}:reset`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCpC,MAAa,mBAAmB;CAC9B,SAAS,GAAG,qBAAqB;CACjC,eAAe,GAAG,qBAAqB;CACvC,SAAS,GAAG,qBAAqB;CACjC,aAAa,GAAG,qBAAqB;CACrC,UAAU,GAAG,qBAAqB;CAClC,WAAW,GAAG,qBAAqB;CACnC,WAAW,GAAG,qBAAqB;CACnC,OAAO,GAAG,qBAAqB;CAChC"}

package/dist/camera/store.d.ts

@@ -84,6 +84,27 @@ declare const cameraStore: MapStore<CameraState, CameraActions>;
  *
  * @param mapId - Unique identifier for the map instance
  * @param initialState - Optional initial camera state
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * import { uuid } from '@accelint/core';
+ * import { initializeCameraState } from '@accelint/map-toolkit/camera';
+ *
+ * const mapId = uuid();
+ *
+ * // Initialize with default state
+ * initializeCameraState(mapId);
+ *
+ * // Initialize with custom state
+ * initializeCameraState(mapId, {
+ *   latitude: 37.7749,
+ *   longitude: -122.4194,
+ *   zoom: 10,
+ *   view: '2.5D',
+ *   pitch: 45,
+ * });
+ * ```
  */
 declare function initializeCameraState(mapId: UniqueId, initialState?: CameraStateInput): void;
 /**
@@ -112,7 +133,33 @@ declare function useMapCamera(mapId: UniqueId, initialCameraState?: CameraStateI
 /**
  * Manually clear camera state for a specific map instance.
  *
+ * Removes all cached state including initial values and subscription tracking.
+ * Useful for cleanup when dynamically destroying map instances.
+ *
  * @param mapId - The unique identifier for the map instance to clear
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * import { clearCameraState } from '@accelint/map-toolkit/camera';
+ *
+ * // Clean up when removing a map
+ * function removeMap(mapId: UniqueId) {
+ *   clearCameraState(mapId);
+ *   // ... remove map component
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { clearCameraState } from '@accelint/map-toolkit/camera';
+ * import { afterEach } from 'vitest';
+ *
+ * // Clean up in tests
+ * afterEach(() => {
+ *   clearCameraState('test-map-id');
+ * });
+ * ```
  */
 declare function clearCameraState(mapId: UniqueId): void;
 //#endregion

package/dist/camera/store.js

@@ -57,6 +57,40 @@ const initializedInstances = /* @__PURE__ */ new Set();
 /**
 * Build a complete camera state from partial input.
 * Returns the appropriate discriminated union variant based on view/projection.
+*
+* This function ensures type-safe camera states by constructing the correct
+* discriminated union variant (2D, 2.5D, or 3D) based on view and projection
+* settings, applying appropriate defaults and constraints.
+*
+* @param partial - Optional partial camera state input
+* @returns Complete camera state matching one of the discriminated union variants
+*
+* @example
+* ```typescript
+* // Build 2D state (default)
+* const state2D = buildCameraState({
+*   latitude: 40.7128,
+*   longitude: -74.0060,
+*   zoom: 10,
+* });
+* // Result: { ..., view: '2D', projection: 'mercator', pitch: 0 }
+*
+* // Build 2.5D state
+* const state2Point5D = buildCameraState({
+*   latitude: 37.7749,
+*   longitude: -122.4194,
+*   zoom: 12,
+*   view: '2.5D',
+* });
+* // Result: { ..., view: '2.5D', projection: 'mercator', pitch: 45 }
+*
+* // Build 3D state
+* const state3D = buildCameraState({
+*   view: '3D',
+*   zoom: 2,
+* });
+* // Result: { ..., view: '3D', projection: 'globe', pitch: 0, rotation: 0 }
+* ```
 */
 function buildCameraState(partial) {
 	const latitude = partial?.latitude ?? 0;
@@ -228,6 +262,27 @@ const cameraStore = createMapStore({
 *
 * @param mapId - Unique identifier for the map instance
 * @param initialState - Optional initial camera state
+* @returns void
+*
+* @example
+* ```typescript
+* import { uuid } from '@accelint/core';
+* import { initializeCameraState } from '@accelint/map-toolkit/camera';
+*
+* const mapId = uuid();
+*
+* // Initialize with default state
+* initializeCameraState(mapId);
+*
+* // Initialize with custom state
+* initializeCameraState(mapId, {
+*   latitude: 37.7749,
+*   longitude: -122.4194,
+*   zoom: 10,
+*   view: '2.5D',
+*   pitch: 45,
+* });
+* ```
 */
 function initializeCameraState(mapId, initialState) {
 	if (initializedInstances.has(mapId)) return;
@@ -266,7 +321,33 @@ function useMapCamera(mapId, initialCameraState) {
 /**
 * Manually clear camera state for a specific map instance.
 *
+* Removes all cached state including initial values and subscription tracking.
+* Useful for cleanup when dynamically destroying map instances.
+*
 * @param mapId - The unique identifier for the map instance to clear
+* @returns void
+*
+* @example
+* ```typescript
+* import { clearCameraState } from '@accelint/map-toolkit/camera';
+*
+* // Clean up when removing a map
+* function removeMap(mapId: UniqueId) {
+*   clearCameraState(mapId);
+*   // ... remove map component
+* }
+* ```
+*
+* @example
+* ```typescript
+* import { clearCameraState } from '@accelint/map-toolkit/camera';
+* import { afterEach } from 'vitest';
+*
+* // Clean up in tests
+* afterEach(() => {
+*   clearCameraState('test-map-id');
+* });
+* ```
 */
 function clearCameraState(mapId) {
 	initializedInstances.delete(mapId);

package/dist/camera/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","names":["DEFAULT_CAMERA_STATE: CameraState"],"sources":["../../src/camera/store.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Camera Store\n *\n * Manages camera state (position, zoom, pitch, rotation, projection, view) per map instance.\n * State is updated via bus events or direct actions.\n *\n * @example\n * ```tsx\n * import { cameraStore } from '@accelint/map-toolkit/camera';\n *\n * function MapInfo({ mapId }) {\n *   const { state } = cameraStore.use(mapId);\n *   return (\n *     <div>\n *       Lat: {state.latitude.toFixed(2)}, Lon: {state.longitude.toFixed(2)}\n *     </div>\n *   );\n * }\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { fitBounds } from '@math.gl/web-mercator';\nimport { createMapStore } from '../shared/create-map-store';\nimport { CameraEventTypes } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { CameraEvent, ProjectionType, ViewType } from './types';\n\nconst cameraBus = Broadcast.getInstance<CameraEvent>();\n\n/**\n * Camera state for 2D view\n */\ntype CameraState2D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'mercator';\n  view: '2D';\n};\n\n/**\n * Camera state for 3D view\n */\ntype CameraState3D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'globe';\n  view: '3D';\n};\n\n/**\n * Camera state for 2.5D view\n */\ntype CameraState2Point5D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: number;\n  rotation: number;\n  projection: 'mercator';\n  view: '2.5D';\n};\n\n/**\n * Union type for all camera states\n */\nexport type CameraState = CameraState2D | CameraState3D | CameraState2Point5D;\n\n/**\n * Actions for camera management\n */\ntype CameraActions = {\n  /** Update camera state directly */\n  setCameraState: (state: Partial<CameraState>) => void;\n};\n\n/**\n * Storage for initial camera state per instance.\n * Used for reset operations to restore to initial values.\n *\n * @internal These caches live outside the store factory because reset operations\n * need access to the original initial values. They are cleaned up via `onCleanup`\n * hook when the store instance is destroyed, and via `clearCameraState()` for\n * manual cleanup. Do NOT use `cameraStore.clear()` directly in tests - use\n * `clearCameraState()` instead to ensure proper cleanup.\n */\nconst initialStateCache = new Map<UniqueId, CameraStateInput>();\n\n/**\n * Track which instances have been initialized.\n * @internal See note on initialStateCache about cleanup.\n */\nconst initializedInstances = new Set<UniqueId>();\n\n/**\n * Input type for building camera state - simpler than union type\n */\ntype CameraStateInput = {\n  latitude?: number;\n  longitude?: number;\n  zoom?: number;\n  pitch?: number;\n  rotation?: number;\n  projection?: ProjectionType;\n  view?: ViewType;\n};\n\n/**\n * Build a complete camera state from partial input.\n * Returns the appropriate discriminated union variant based on view/projection.\n */\nfunction buildCameraState(partial?: CameraStateInput): CameraState {\n  const latitude = partial?.latitude ?? 0;\n  const longitude = partial?.longitude ?? 0;\n  const zoom = partial?.zoom ?? 0;\n  const rotation = partial?.rotation ?? 0;\n\n  // Determine which variant to build based on view/projection\n  const is3D = partial?.view === '3D' || partial?.projection === 'globe';\n  const is2Point5D = partial?.view === '2.5D';\n\n  if (is3D) {\n    // 3D view: globe projection, no pitch, no rotation\n    return {\n      latitude,\n      longitude,\n      zoom,\n      pitch: 0,\n      rotation: 0,\n      projection: 'globe',\n      view: '3D',\n    } satisfies CameraState3D;\n  }\n\n  if (is2Point5D) {\n    // 2.5D view: mercator projection, variable pitch\n    return {\n      latitude,\n      longitude,\n      zoom,\n      pitch: partial?.pitch ?? 45,\n      rotation,\n      projection: 'mercator',\n      view: '2.5D',\n    } satisfies CameraState2Point5D;\n  }\n\n  // Default: 2D view, mercator projection, no pitch\n  return {\n    latitude,\n    longitude,\n    zoom,\n    pitch: 0,\n    rotation,\n    projection: 'mercator',\n    view: '2D',\n  } satisfies CameraState2D;\n}\n\n/**\n * Default camera state\n */\nconst DEFAULT_CAMERA_STATE: CameraState = {\n  latitude: 0,\n  longitude: 0,\n  zoom: 0,\n  pitch: 0,\n  rotation: 0,\n  projection: 'mercator',\n  view: '2D',\n};\n\n/**\n * Camera store instance\n */\nexport const cameraStore = createMapStore<CameraState, CameraActions>({\n  defaultState: DEFAULT_CAMERA_STATE,\n\n  actions: (_mapId, { get, replace }) => ({\n    setCameraState: (updates: Partial<CameraState>) => {\n      const currentState = get();\n      // Use buildCameraState to ensure proper discriminated union type\n      replace(buildCameraState({ ...currentState, ...updates }));\n    },\n  }),\n\n  bus: (mapId, { get, replace }) => {\n    const unsubReset = cameraBus.on(CameraEventTypes.reset, ({ payload }) => {\n      if (payload.id !== mapId) {\n        return;\n      }\n\n      const state = get();\n      const initialState = initialStateCache.get(mapId);\n      const newState = buildCameraState({\n        latitude: state.latitude,\n        longitude: state.longitude,\n        projection: state.projection,\n        view: state.view,\n        zoom: payload.zoom === false ? state.zoom : (initialState?.zoom ?? 0),\n        pitch:\n          payload.pitch === false ? state.pitch : (initialState?.pitch ?? 0),\n        rotation:\n          payload.rotation === false\n            ? state.rotation\n            : (initialState?.rotation ?? 0),\n      });\n\n      replace(newState);\n    });\n\n    const unsubSetCenter = cameraBus.on(\n      CameraEventTypes.setCenter,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        replace(\n          buildCameraState({\n            ...state,\n            latitude: payload.latitude,\n            longitude: payload.longitude,\n            zoom: payload.zoom ?? state.zoom,\n            rotation: payload.heading ?? state.rotation,\n            pitch: payload.pitch ?? state.pitch,\n          }),\n        );\n      },\n    );\n\n    const unsubFitBounds = cameraBus.on(\n      CameraEventTypes.fitBounds,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const { longitude, latitude, zoom } = fitBounds({\n          width: payload.width,\n          height: payload.height,\n          bounds: [\n            [payload.bounds[0], payload.bounds[1]],\n            [payload.bounds[2], payload.bounds[3]],\n          ],\n          padding: payload.padding,\n        });\n\n        replace(\n          buildCameraState({\n            ...state,\n            latitude,\n            longitude,\n            zoom,\n            rotation: payload.heading ?? state.rotation,\n            pitch: payload.pitch ?? state.pitch,\n          }),\n        );\n      },\n    );\n\n    const unsubSetProjection = cameraBus.on(\n      CameraEventTypes.setProjection,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const newState = { ...state };\n        newState.projection = payload.projection;\n        if (payload.projection === 'globe') {\n          newState.view = '3D';\n        } else {\n          newState.view = '2D';\n          newState.pitch = 0;\n        }\n        replace(newState);\n      },\n    );\n\n    const unsubSetView = cameraBus.on(\n      CameraEventTypes.setView,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const newState = { ...state };\n        newState.view = payload.view;\n        if (payload.view === '3D') {\n          newState.projection = 'globe';\n          newState.pitch = 0;\n        } else {\n          newState.projection = 'mercator';\n        }\n\n        if (payload.view === '2.5D') {\n          newState.pitch = 45;\n        }\n        replace(newState);\n      },\n    );\n\n    const unsubSetZoom = cameraBus.on(\n      CameraEventTypes.setZoom,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        replace({ ...state, zoom: payload.zoom });\n      },\n    );\n\n    const unsubSetRotation = cameraBus.on(\n      CameraEventTypes.setRotation,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        if (state.view !== '3D') {\n          replace({ ...state, rotation: payload.rotation });\n        }\n      },\n    );\n\n    const unsubSetPitch = cameraBus.on(\n      CameraEventTypes.setPitch,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        if (state.view === '2.5D') {\n          replace({ ...state, pitch: payload.pitch });\n        }\n      },\n    );\n\n    return () => {\n      unsubReset();\n      unsubSetCenter();\n      unsubFitBounds();\n      unsubSetProjection();\n      unsubSetView();\n      unsubSetZoom();\n      unsubSetRotation();\n      unsubSetPitch();\n    };\n  },\n\n  onCleanup: (mapId) => {\n    initializedInstances.delete(mapId);\n    initialStateCache.delete(mapId);\n  },\n});\n\n// =============================================================================\n// Convenience exports\n// =============================================================================\n\n/**\n * Initialize camera state for a map instance with optional initial values.\n * Should be called before using the camera store for a given mapId.\n *\n * @param mapId - Unique identifier for the map instance\n * @param initialState - Optional initial camera state\n */\nexport function initializeCameraState(\n  mapId: UniqueId,\n  initialState?: CameraStateInput,\n): void {\n  if (initializedInstances.has(mapId)) {\n    return; // Already initialized\n  }\n\n  initializedInstances.add(mapId);\n  if (initialState) {\n    initialStateCache.set(mapId, initialState);\n  }\n  const builtState = buildCameraState(initialState);\n  cameraStore.set(mapId, builtState);\n}\n\n/**\n * Hook to subscribe to camera state changes for a specific map.\n *\n * @param mapId - Unique identifier for the map instance\n * @param initialCameraState - Optional initial camera state (only used on first call)\n * @returns Camera state and setCameraState action\n *\n * @example\n * ```tsx\n * function MapInfo({ mapId }) {\n *   const { cameraState, setCameraState } = useMapCamera(mapId);\n *   return (\n *     <div>\n *       Lat: {cameraState.latitude.toFixed(2)}, Lon: {cameraState.longitude.toFixed(2)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useMapCamera(\n  mapId: UniqueId,\n  initialCameraState?: CameraStateInput,\n): {\n  cameraState: CameraState;\n  setCameraState: (state: Partial<CameraState>) => void;\n} {\n  // Initialize on first use if initial state provided\n  if (initialCameraState && !initializedInstances.has(mapId)) {\n    initializeCameraState(mapId, initialCameraState);\n  }\n\n  const { state, setCameraState } = cameraStore.use(mapId);\n\n  return { cameraState: state, setCameraState };\n}\n\n/**\n * Manually clear camera state for a specific map instance.\n *\n * @param mapId - The unique identifier for the map instance to clear\n */\nexport function clearCameraState(mapId: UniqueId): void {\n  initializedInstances.delete(mapId);\n  initialStateCache.delete(mapId);\n  cameraStore.clear(mapId);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAM,YAAY,UAAU,aAA0B;;;;;;;;;;;AAgEtD,MAAM,oCAAoB,IAAI,KAAiC;;;;;AAM/D,MAAM,uCAAuB,IAAI,KAAe;;;;;AAmBhD,SAAS,iBAAiB,SAAyC;CACjE,MAAM,WAAW,SAAS,YAAY;CACtC,MAAM,YAAY,SAAS,aAAa;CACxC,MAAM,OAAO,SAAS,QAAQ;CAC9B,MAAM,WAAW,SAAS,YAAY;CAGtC,MAAM,OAAO,SAAS,SAAS,QAAQ,SAAS,eAAe;CAC/D,MAAM,aAAa,SAAS,SAAS;AAErC,KAAI,KAEF,QAAO;EACL;EACA;EACA;EACA,OAAO;EACP,UAAU;EACV,YAAY;EACZ,MAAM;EACP;AAGH,KAAI,WAEF,QAAO;EACL;EACA;EACA;EACA,OAAO,SAAS,SAAS;EACzB;EACA,YAAY;EACZ,MAAM;EACP;AAIH,QAAO;EACL;EACA;EACA;EACA,OAAO;EACP;EACA,YAAY;EACZ,MAAM;EACP;;;;;AAMH,MAAMA,uBAAoC;CACxC,UAAU;CACV,WAAW;CACX,MAAM;CACN,OAAO;CACP,UAAU;CACV,YAAY;CACZ,MAAM;CACP;;;;AAKD,MAAa,cAAc,eAA2C;CACpE,cAAc;CAEd,UAAU,QAAQ,EAAE,KAAK,eAAe,EACtC,iBAAiB,YAAkC;AAGjD,UAAQ,iBAAiB;GAAE,GAFN,KAAK;GAEkB,GAAG;GAAS,CAAC,CAAC;IAE7D;CAED,MAAM,OAAO,EAAE,KAAK,cAAc;EAChC,MAAM,aAAa,UAAU,GAAG,iBAAiB,QAAQ,EAAE,cAAc;AACvE,OAAI,QAAQ,OAAO,MACjB;GAGF,MAAM,QAAQ,KAAK;GACnB,MAAM,eAAe,kBAAkB,IAAI,MAAM;AAejD,WAdiB,iBAAiB;IAChC,UAAU,MAAM;IAChB,WAAW,MAAM;IACjB,YAAY,MAAM;IAClB,MAAM,MAAM;IACZ,MAAM,QAAQ,SAAS,QAAQ,MAAM,OAAQ,cAAc,QAAQ;IACnE,OACE,QAAQ,UAAU,QAAQ,MAAM,QAAS,cAAc,SAAS;IAClE,UACE,QAAQ,aAAa,QACjB,MAAM,WACL,cAAc,YAAY;IAClC,CAAC,CAEe;IACjB;EAEF,MAAM,iBAAiB,UAAU,GAC/B,iBAAiB,YAChB,EAAE,cAAc;AACf,OAAI,QAAQ,OAAO,MACjB;GAGF,MAAM,QAAQ,KAAK;AACnB,WACE,iBAAiB;IACf,GAAG;IACH,UAAU,QAAQ;IAClB,WAAW,QAAQ;IACnB,MAAM,QAAQ,QAAQ,MAAM;IAC5B,UAAU,QAAQ,WAAW,MAAM;IACnC,OAAO,QAAQ,SAAS,MAAM;IAC/B,CAAC,CACH;IAEJ;EAED,MAAM,iBAAiB,UAAU,GAC/B,iBAAiB,YAChB,EAAE,cAAc;AACf,OAAI,QAAQ,OAAO,MACjB;GAGF,MAAM,QAAQ,KAAK;GACnB,MAAM,EAAE,WAAW,UAAU,SAAS,UAAU;IAC9C,OAAO,QAAQ;IACf,QAAQ,QAAQ;IAChB,QAAQ,CACN,CAAC,QAAQ,OAAO,IAAI,QAAQ,OAAO,GAAG,EACtC,CAAC,QAAQ,OAAO,IAAI,QAAQ,OAAO,GAAG,CACvC;IACD,SAAS,QAAQ;IAClB,CAAC;AAEF,WACE,iBAAiB;IACf,GAAG;IACH;IACA;IACA;IACA,UAAU,QAAQ,WAAW,MAAM;IACnC,OAAO,QAAQ,SAAS,MAAM;IAC/B,CAAC,CACH;IAEJ;EAED,MAAM,qBAAqB,UAAU,GACnC,iBAAiB,gBAChB,EAAE,cAAc;AACf,OAAI,QAAQ,OAAO,MACjB;GAIF,MAAM,WAAW,EAAE,GADL,KAAK,EACU;AAC7B,YAAS,aAAa,QAAQ;AAC9B,OAAI,QAAQ,eAAe,QACzB,UAAS,OAAO;QACX;AACL,aAAS,OAAO;AAChB,aAAS,QAAQ;;AAEnB,WAAQ,SAAS;IAEpB;EAED,MAAM,eAAe,UAAU,GAC7B,iBAAiB,UAChB,EAAE,cAAc;AACf,OAAI,QAAQ,OAAO,MACjB;GAIF,MAAM,WAAW,EAAE,GADL,KAAK,EACU;AAC7B,YAAS,OAAO,QAAQ;AACxB,OAAI,QAAQ,SAAS,MAAM;AACzB,aAAS,aAAa;AACtB,aAAS,QAAQ;SAEjB,UAAS,aAAa;AAGxB,OAAI,QAAQ,SAAS,OACnB,UAAS,QAAQ;AAEnB,WAAQ,SAAS;IAEpB;EAED,MAAM,eAAe,UAAU,GAC7B,iBAAiB,UAChB,EAAE,cAAc;AACf,OAAI,QAAQ,OAAO,MACjB;AAIF,WAAQ;IAAE,GADI,KAAK;IACC,MAAM,QAAQ;IAAM,CAAC;IAE5C;EAED,MAAM,mBAAmB,UAAU,GACjC,iBAAiB,cAChB,EAAE,cAAc;AACf,OAAI,QAAQ,OAAO,MACjB;GAGF,MAAM,QAAQ,KAAK;AACnB,OAAI,MAAM,SAAS,KACjB,SAAQ;IAAE,GAAG;IAAO,UAAU,QAAQ;IAAU,CAAC;IAGtD;EAED,MAAM,gBAAgB,UAAU,GAC9B,iBAAiB,WAChB,EAAE,cAAc;AACf,OAAI,QAAQ,OAAO,MACjB;GAGF,MAAM,QAAQ,KAAK;AACnB,OAAI,MAAM,SAAS,OACjB,SAAQ;IAAE,GAAG;IAAO,OAAO,QAAQ;IAAO,CAAC;IAGhD;AAED,eAAa;AACX,eAAY;AACZ,mBAAgB;AAChB,mBAAgB;AAChB,uBAAoB;AACpB,iBAAc;AACd,iBAAc;AACd,qBAAkB;AAClB,kBAAe;;;CAInB,YAAY,UAAU;AACpB,uBAAqB,OAAO,MAAM;AAClC,oBAAkB,OAAO,MAAM;;CAElC,CAAC;;;;;;;;AAaF,SAAgB,sBACd,OACA,cACM;AACN,KAAI,qBAAqB,IAAI,MAAM,CACjC;AAGF,sBAAqB,IAAI,MAAM;AAC/B,KAAI,aACF,mBAAkB,IAAI,OAAO,aAAa;CAE5C,MAAM,aAAa,iBAAiB,aAAa;AACjD,aAAY,IAAI,OAAO,WAAW;;;;;;;;;;;;;;;;;;;;;AAsBpC,SAAgB,aACd,OACA,oBAIA;AAEA,KAAI,sBAAsB,CAAC,qBAAqB,IAAI,MAAM,CACxD,uBAAsB,OAAO,mBAAmB;CAGlD,MAAM,EAAE,OAAO,mBAAmB,YAAY,IAAI,MAAM;AAExD,QAAO;EAAE,aAAa;EAAO;EAAgB;;;;;;;AAQ/C,SAAgB,iBAAiB,OAAuB;AACtD,sBAAqB,OAAO,MAAM;AAClC,mBAAkB,OAAO,MAAM;AAC/B,aAAY,MAAM,MAAM"}
+{"version":3,"file":"store.js","names":["DEFAULT_CAMERA_STATE: CameraState"],"sources":["../../src/camera/store.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Camera Store\n *\n * Manages camera state (position, zoom, pitch, rotation, projection, view) per map instance.\n * State is updated via bus events or direct actions.\n *\n * @example\n * ```tsx\n * import { cameraStore } from '@accelint/map-toolkit/camera';\n *\n * function MapInfo({ mapId }) {\n *   const { state } = cameraStore.use(mapId);\n *   return (\n *     <div>\n *       Lat: {state.latitude.toFixed(2)}, Lon: {state.longitude.toFixed(2)}\n *     </div>\n *   );\n * }\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { fitBounds } from '@math.gl/web-mercator';\nimport { createMapStore } from '../shared/create-map-store';\nimport { CameraEventTypes } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { CameraEvent, ProjectionType, ViewType } from './types';\n\nconst cameraBus = Broadcast.getInstance<CameraEvent>();\n\n/**\n * Camera state for 2D view\n */\ntype CameraState2D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'mercator';\n  view: '2D';\n};\n\n/**\n * Camera state for 3D view\n */\ntype CameraState3D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: 0;\n  rotation: number;\n  projection: 'globe';\n  view: '3D';\n};\n\n/**\n * Camera state for 2.5D view\n */\ntype CameraState2Point5D = {\n  latitude: number;\n  longitude: number;\n  zoom: number;\n  pitch: number;\n  rotation: number;\n  projection: 'mercator';\n  view: '2.5D';\n};\n\n/**\n * Union type for all camera states\n */\nexport type CameraState = CameraState2D | CameraState3D | CameraState2Point5D;\n\n/**\n * Actions for camera management\n */\ntype CameraActions = {\n  /** Update camera state directly */\n  setCameraState: (state: Partial<CameraState>) => void;\n};\n\n/**\n * Storage for initial camera state per instance.\n * Used for reset operations to restore to initial values.\n *\n * @internal These caches live outside the store factory because reset operations\n * need access to the original initial values. They are cleaned up via `onCleanup`\n * hook when the store instance is destroyed, and via `clearCameraState()` for\n * manual cleanup. Do NOT use `cameraStore.clear()` directly in tests - use\n * `clearCameraState()` instead to ensure proper cleanup.\n */\nconst initialStateCache = new Map<UniqueId, CameraStateInput>();\n\n/**\n * Track which instances have been initialized.\n * @internal See note on initialStateCache about cleanup.\n */\nconst initializedInstances = new Set<UniqueId>();\n\n/**\n * Input type for building camera state - simpler than union type\n */\ntype CameraStateInput = {\n  latitude?: number;\n  longitude?: number;\n  zoom?: number;\n  pitch?: number;\n  rotation?: number;\n  projection?: ProjectionType;\n  view?: ViewType;\n};\n\n/**\n * Build a complete camera state from partial input.\n * Returns the appropriate discriminated union variant based on view/projection.\n *\n * This function ensures type-safe camera states by constructing the correct\n * discriminated union variant (2D, 2.5D, or 3D) based on view and projection\n * settings, applying appropriate defaults and constraints.\n *\n * @param partial - Optional partial camera state input\n * @returns Complete camera state matching one of the discriminated union variants\n *\n * @example\n * ```typescript\n * // Build 2D state (default)\n * const state2D = buildCameraState({\n *   latitude: 40.7128,\n *   longitude: -74.0060,\n *   zoom: 10,\n * });\n * // Result: { ..., view: '2D', projection: 'mercator', pitch: 0 }\n *\n * // Build 2.5D state\n * const state2Point5D = buildCameraState({\n *   latitude: 37.7749,\n *   longitude: -122.4194,\n *   zoom: 12,\n *   view: '2.5D',\n * });\n * // Result: { ..., view: '2.5D', projection: 'mercator', pitch: 45 }\n *\n * // Build 3D state\n * const state3D = buildCameraState({\n *   view: '3D',\n *   zoom: 2,\n * });\n * // Result: { ..., view: '3D', projection: 'globe', pitch: 0, rotation: 0 }\n * ```\n */\nfunction buildCameraState(partial?: CameraStateInput): CameraState {\n  const latitude = partial?.latitude ?? 0;\n  const longitude = partial?.longitude ?? 0;\n  const zoom = partial?.zoom ?? 0;\n  const rotation = partial?.rotation ?? 0;\n\n  // Determine which variant to build based on view/projection\n  const is3D = partial?.view === '3D' || partial?.projection === 'globe';\n  const is2Point5D = partial?.view === '2.5D';\n\n  if (is3D) {\n    // 3D view: globe projection, no pitch, no rotation\n    return {\n      latitude,\n      longitude,\n      zoom,\n      pitch: 0,\n      rotation: 0,\n      projection: 'globe',\n      view: '3D',\n    } satisfies CameraState3D;\n  }\n\n  if (is2Point5D) {\n    // 2.5D view: mercator projection, variable pitch\n    return {\n      latitude,\n      longitude,\n      zoom,\n      pitch: partial?.pitch ?? 45,\n      rotation,\n      projection: 'mercator',\n      view: '2.5D',\n    } satisfies CameraState2Point5D;\n  }\n\n  // Default: 2D view, mercator projection, no pitch\n  return {\n    latitude,\n    longitude,\n    zoom,\n    pitch: 0,\n    rotation,\n    projection: 'mercator',\n    view: '2D',\n  } satisfies CameraState2D;\n}\n\n/**\n * Default camera state\n */\nconst DEFAULT_CAMERA_STATE: CameraState = {\n  latitude: 0,\n  longitude: 0,\n  zoom: 0,\n  pitch: 0,\n  rotation: 0,\n  projection: 'mercator',\n  view: '2D',\n};\n\n/**\n * Camera store instance\n */\nexport const cameraStore = createMapStore<CameraState, CameraActions>({\n  defaultState: DEFAULT_CAMERA_STATE,\n\n  actions: (_mapId, { get, replace }) => ({\n    setCameraState: (updates: Partial<CameraState>) => {\n      const currentState = get();\n      // Use buildCameraState to ensure proper discriminated union type\n      replace(buildCameraState({ ...currentState, ...updates }));\n    },\n  }),\n\n  bus: (mapId, { get, replace }) => {\n    const unsubReset = cameraBus.on(CameraEventTypes.reset, ({ payload }) => {\n      if (payload.id !== mapId) {\n        return;\n      }\n\n      const state = get();\n      const initialState = initialStateCache.get(mapId);\n      const newState = buildCameraState({\n        latitude: state.latitude,\n        longitude: state.longitude,\n        projection: state.projection,\n        view: state.view,\n        zoom: payload.zoom === false ? state.zoom : (initialState?.zoom ?? 0),\n        pitch:\n          payload.pitch === false ? state.pitch : (initialState?.pitch ?? 0),\n        rotation:\n          payload.rotation === false\n            ? state.rotation\n            : (initialState?.rotation ?? 0),\n      });\n\n      replace(newState);\n    });\n\n    const unsubSetCenter = cameraBus.on(\n      CameraEventTypes.setCenter,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        replace(\n          buildCameraState({\n            ...state,\n            latitude: payload.latitude,\n            longitude: payload.longitude,\n            zoom: payload.zoom ?? state.zoom,\n            rotation: payload.heading ?? state.rotation,\n            pitch: payload.pitch ?? state.pitch,\n          }),\n        );\n      },\n    );\n\n    const unsubFitBounds = cameraBus.on(\n      CameraEventTypes.fitBounds,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const { longitude, latitude, zoom } = fitBounds({\n          width: payload.width,\n          height: payload.height,\n          bounds: [\n            [payload.bounds[0], payload.bounds[1]],\n            [payload.bounds[2], payload.bounds[3]],\n          ],\n          padding: payload.padding,\n        });\n\n        replace(\n          buildCameraState({\n            ...state,\n            latitude,\n            longitude,\n            zoom,\n            rotation: payload.heading ?? state.rotation,\n            pitch: payload.pitch ?? state.pitch,\n          }),\n        );\n      },\n    );\n\n    const unsubSetProjection = cameraBus.on(\n      CameraEventTypes.setProjection,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const newState = { ...state };\n        newState.projection = payload.projection;\n        if (payload.projection === 'globe') {\n          newState.view = '3D';\n        } else {\n          newState.view = '2D';\n          newState.pitch = 0;\n        }\n        replace(newState);\n      },\n    );\n\n    const unsubSetView = cameraBus.on(\n      CameraEventTypes.setView,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const newState = { ...state };\n        newState.view = payload.view;\n        if (payload.view === '3D') {\n          newState.projection = 'globe';\n          newState.pitch = 0;\n        } else {\n          newState.projection = 'mercator';\n        }\n\n        if (payload.view === '2.5D') {\n          newState.pitch = 45;\n        }\n        replace(newState);\n      },\n    );\n\n    const unsubSetZoom = cameraBus.on(\n      CameraEventTypes.setZoom,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        replace({ ...state, zoom: payload.zoom });\n      },\n    );\n\n    const unsubSetRotation = cameraBus.on(\n      CameraEventTypes.setRotation,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        if (state.view !== '3D') {\n          replace({ ...state, rotation: payload.rotation });\n        }\n      },\n    );\n\n    const unsubSetPitch = cameraBus.on(\n      CameraEventTypes.setPitch,\n      ({ payload }) => {\n        if (payload.id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        if (state.view === '2.5D') {\n          replace({ ...state, pitch: payload.pitch });\n        }\n      },\n    );\n\n    return () => {\n      unsubReset();\n      unsubSetCenter();\n      unsubFitBounds();\n      unsubSetProjection();\n      unsubSetView();\n      unsubSetZoom();\n      unsubSetRotation();\n      unsubSetPitch();\n    };\n  },\n\n  onCleanup: (mapId) => {\n    initializedInstances.delete(mapId);\n    initialStateCache.delete(mapId);\n  },\n});\n\n// =============================================================================\n// Convenience exports\n// =============================================================================\n\n/**\n * Initialize camera state for a map instance with optional initial values.\n * Should be called before using the camera store for a given mapId.\n *\n * @param mapId - Unique identifier for the map instance\n * @param initialState - Optional initial camera state\n * @returns void\n *\n * @example\n * ```typescript\n * import { uuid } from '@accelint/core';\n * import { initializeCameraState } from '@accelint/map-toolkit/camera';\n *\n * const mapId = uuid();\n *\n * // Initialize with default state\n * initializeCameraState(mapId);\n *\n * // Initialize with custom state\n * initializeCameraState(mapId, {\n *   latitude: 37.7749,\n *   longitude: -122.4194,\n *   zoom: 10,\n *   view: '2.5D',\n *   pitch: 45,\n * });\n * ```\n */\nexport function initializeCameraState(\n  mapId: UniqueId,\n  initialState?: CameraStateInput,\n): void {\n  if (initializedInstances.has(mapId)) {\n    return; // Already initialized\n  }\n\n  initializedInstances.add(mapId);\n  if (initialState) {\n    initialStateCache.set(mapId, initialState);\n  }\n  const builtState = buildCameraState(initialState);\n  cameraStore.set(mapId, builtState);\n}\n\n/**\n * Hook to subscribe to camera state changes for a specific map.\n *\n * @param mapId - Unique identifier for the map instance\n * @param initialCameraState - Optional initial camera state (only used on first call)\n * @returns Camera state and setCameraState action\n *\n * @example\n * ```tsx\n * function MapInfo({ mapId }) {\n *   const { cameraState, setCameraState } = useMapCamera(mapId);\n *   return (\n *     <div>\n *       Lat: {cameraState.latitude.toFixed(2)}, Lon: {cameraState.longitude.toFixed(2)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useMapCamera(\n  mapId: UniqueId,\n  initialCameraState?: CameraStateInput,\n): {\n  cameraState: CameraState;\n  setCameraState: (state: Partial<CameraState>) => void;\n} {\n  // Initialize on first use if initial state provided\n  if (initialCameraState && !initializedInstances.has(mapId)) {\n    initializeCameraState(mapId, initialCameraState);\n  }\n\n  const { state, setCameraState } = cameraStore.use(mapId);\n\n  return { cameraState: state, setCameraState };\n}\n\n/**\n * Manually clear camera state for a specific map instance.\n *\n * Removes all cached state including initial values and subscription tracking.\n * Useful for cleanup when dynamically destroying map instances.\n *\n * @param mapId - The unique identifier for the map instance to clear\n * @returns void\n *\n * @example\n * ```typescript\n * import { clearCameraState } from '@accelint/map-toolkit/camera';\n *\n * // Clean up when removing a map\n * function removeMap(mapId: UniqueId) {\n *   clearCameraState(mapId);\n *   // ... remove map component\n * }\n * ```\n *\n * @example\n * ```typescript\n * import { clearCameraState } from '@accelint/map-toolkit/camera';\n * import { afterEach } from 'vitest';\n *\n * // Clean up in tests\n * afterEach(() => {\n *   clearCameraState('test-map-id');\n * });\n * ```\n */\nexport function clearCameraState(mapId: UniqueId): void {\n  initializedInstances.delete(mapId);\n  initialStateCache.delete(mapId);\n  cameraStore.clear(mapId);\n}\n"],"mappings":"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"}

package/dist/camera/types.d.ts

@@ -16,8 +16,24 @@ import { Payload } from "@accelint/bus";
 import { UniqueId } from "@accelint/core/utility/uuid";
 
 //#region src/camera/types.d.ts
+/**
+ * Map projection types supported by the camera system.
+ *
+ * - `mercator`: Web Mercator projection for 2D and 2.5D views
+ * - `globe`: Spherical globe projection for 3D views
+ */
 type ProjectionType = 'mercator' | 'globe';
+/**
+ * Camera view modes defining perspective and interaction capabilities.
+ *
+ * - `2D`: Traditional flat map view with rotation
+ * - `2.5D`: Tilted perspective view with pitch and rotation
+ * - `3D`: Globe view with fixed orientation
+ */
 type ViewType = '2D' | '2.5D' | '3D';
+/**
+ * Payload for setting camera center position.
+ */
 type CameraSetCenterPayload = {
   /** Identifier of the camera */
   id: UniqueId;
@@ -32,6 +48,9 @@ type CameraSetCenterPayload = {
   /** Optional pitch angle */
   pitch?: number;
 };
+/**
+ * Payload for fitting camera to show a bounding box.
+ */
 type CameraFitBoundsPayload = {
   /** Identifier of the camera */
   id: UniqueId;
@@ -48,36 +67,98 @@ type CameraFitBoundsPayload = {
   /** Optional pitch angle */
   pitch?: number;
 };
+/**
+ * Payload for resetting camera to initial state.
+ *
+ * Set property to `false` to preserve that property during reset.
+ * By default, all properties are reset to initial values.
+ *
+ * @example
+ * ```typescript
+ * import type { CameraResetPayload } from '@accelint/map-toolkit/camera';
+ *
+ * // Full reset
+ * const fullReset: CameraResetPayload = {
+ *   id: 'map-1',
+ * };
+ *
+ * // Reset but keep current zoom
+ * const keepZoom: CameraResetPayload = {
+ *   id: 'map-1',
+ *   zoom: false,
+ * };
+ * ```
+ */
 type CameraResetPayload = {
   /** Identifier of the camera */
   id: UniqueId;
+  /** Set to false to preserve current zoom during reset */
   zoom?: boolean;
+  /** Set to false to preserve current pitch during reset */
   pitch?: boolean;
+  /** Set to false to preserve current rotation during reset */
   rotation?: boolean;
 };
+/**
+ * Event type for setting camera center position.
+ */
 type CameraSetCenterEvent = Payload<typeof CameraEventTypes.setCenter, CameraSetCenterPayload>;
+/**
+ * Event type for fitting camera to bounds.
+ */
 type CameraFitBoundsEvent = Payload<typeof CameraEventTypes.fitBounds, CameraFitBoundsPayload>;
+/**
+ * Event type for setting camera projection.
+ */
 type CameraSetProjectionEvent = Payload<typeof CameraEventTypes.setProjection, {
   id: UniqueId;
   projection: ProjectionType;
 }>;
+/**
+ * Event type for setting camera view mode.
+ */
 type CameraSetViewEvent = Payload<typeof CameraEventTypes.setView, {
   id: UniqueId;
   view: ViewType;
 }>;
+/**
+ * Event type for setting camera zoom level.
+ */
 type CameraSetZoomEvent = Payload<typeof CameraEventTypes.setZoom, {
   id: UniqueId;
   zoom: number;
 }>;
+/**
+ * Event type for setting camera rotation angle.
+ */
 type CameraSetRotationEvent = Payload<typeof CameraEventTypes.setRotation, {
   id: UniqueId;
   rotation: number;
 }>;
+/**
+ * Event type for setting camera pitch angle.
+ */
 type CameraSetPitchEvent = Payload<typeof CameraEventTypes.setPitch, {
   id: UniqueId;
   pitch: number;
 }>;
+/**
+ * Event type for resetting camera to initial state.
+ */
 type CameraResetEvent = Payload<typeof CameraEventTypes.reset, CameraResetPayload>;
+/**
+ * Union type of all camera events.
+ *
+ * Use this type when registering bus listeners that handle multiple camera events.
+ *
+ * @example
+ * ```typescript
+ * import { Broadcast } from '@accelint/bus';
+ * import type { CameraEvent } from '@accelint/map-toolkit/camera';
+ *
+ * const bus = Broadcast.getInstance<CameraEvent>();
+ * ```
+ */
 type CameraEvent = CameraSetCenterEvent | CameraFitBoundsEvent | CameraSetProjectionEvent | CameraSetViewEvent | CameraSetZoomEvent | CameraSetRotationEvent | CameraSetPitchEvent | CameraResetEvent;
 //#endregion
 export { CameraEvent, CameraFitBoundsEvent, CameraFitBoundsPayload, CameraResetEvent, CameraResetPayload, CameraSetCenterEvent, CameraSetCenterPayload, CameraSetPitchEvent, CameraSetProjectionEvent, CameraSetRotationEvent, CameraSetViewEvent, CameraSetZoomEvent, ProjectionType, ViewType };

package/dist/cursor-coordinates/constants.d.ts

@@ -0,0 +1,8 @@
+//#region src/cursor-coordinates/constants.d.ts
+declare const MAX_LONGITUDE = 180;
+declare const LONGITUDE_RANGE = 360;
+declare const DEFAULT_LATLON_COORDS = "--, --";
+declare const DEFAULT_MGRS_UTM_COORDS = "--- -- ---- ----";
+//#endregion
+export { DEFAULT_LATLON_COORDS, DEFAULT_MGRS_UTM_COORDS, LONGITUDE_RANGE, MAX_LONGITUDE };
+//# sourceMappingURL=constants.d.ts.map

package/dist/cursor-coordinates/constants.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+//#region src/cursor-coordinates/constants.ts
+const MAX_LONGITUDE = 180;
+const LONGITUDE_RANGE = 360;
+const DEFAULT_LATLON_COORDS = "--, --";
+const DEFAULT_MGRS_UTM_COORDS = "--- -- ---- ----";
+
+//#endregion
+export { DEFAULT_LATLON_COORDS, DEFAULT_MGRS_UTM_COORDS, LONGITUDE_RANGE, MAX_LONGITUDE };
+//# sourceMappingURL=constants.js.map

package/dist/cursor-coordinates/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../../src/cursor-coordinates/constants.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const MAX_LONGITUDE = 180;\nexport const LONGITUDE_RANGE = 360;\nexport const DEFAULT_LATLON_COORDS = '--, --';\nexport const DEFAULT_MGRS_UTM_COORDS = '--- -- ---- ----';\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAa,gBAAgB;AAC7B,MAAa,kBAAkB;AAC/B,MAAa,wBAAwB;AACrC,MAAa,0BAA0B"}

package/dist/cursor-coordinates/store.d.ts

@@ -35,6 +35,7 @@ declare const cursorCoordinateStore: MapStore<CursorCoordinateState, CursorCoord
  * Use this only in advanced scenarios where manual cleanup is required.
  *
  * @param instanceId - The unique identifier for the map to clear
+ * @returns void
  *
  * @example
  * ```tsx

package/dist/cursor-coordinates/store.js

@@ -76,6 +76,7 @@ const cursorCoordinateStore = createMapStore({
 * Use this only in advanced scenarios where manual cleanup is required.
 *
 * @param instanceId - The unique identifier for the map to clear
+* @returns void
 *
 * @example
 * ```tsx

package/dist/cursor-coordinates/store.js.map

@@ -1 +1 @@
-{"version":3,"file":"store.js","names":[],"sources":["../../src/cursor-coordinates/store.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Cursor Coordinates Store\n *\n * Manages cursor coordinate state for map instances using the shared store factory.\n * Subscribes to hover events from the map and stores the current cursor position.\n *\n * @example\n * ```tsx\n * import { cursorCoordinateStore } from './store';\n *\n * // Use in a component\n * function CoordinateDisplay({ mapId }) {\n *   const { state, setFormat } = cursorCoordinateStore.use(mapId);\n *   return <div>{state.coordinate ? `${state.coordinate[0]}, ${state.coordinate[1]}` : '--'}</div>;\n * }\n *\n * // Or use the selector for specific values\n * const coord = cursorCoordinateStore.useSelector(mapId, (s) => s.coordinate);\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { MapEvents } from '../deckgl/base-map/events';\nimport { createMapStore } from '../shared/create-map-store';\nimport type { UniqueId } from '@accelint/core';\nimport type { MapEventType, MapHoverEvent } from '../deckgl/base-map/types';\nimport type { CoordinateFormatTypes, CursorCoordinateState } from './types';\n\nconst bus = Broadcast.getInstance<MapEventType>();\n\n/**\n * Type guard to validate that a value is a proper coordinate tuple.\n * Checks that the value is an array with exactly two finite numbers.\n *\n * @param value - Value to validate as a coordinate\n * @returns True if value is a valid [longitude, latitude] tuple\n */\nfunction isValidCoordinate(value?: number[]): value is [number, number] {\n  return (\n    Array.isArray(value) && value.length === 2 && value.every(Number.isFinite)\n  );\n}\n\n/**\n * Actions for cursor coordinate management\n */\ntype CursorCoordinateActions = {\n  /** Set the coordinate display format */\n  setFormat: (format: CoordinateFormatTypes) => void;\n};\n\n/**\n * Cursor coordinates store\n *\n * Stores the current cursor position and display format for each map instance.\n * Automatically subscribes to hover events when first React subscriber mounts.\n */\nexport const cursorCoordinateStore = createMapStore<\n  CursorCoordinateState,\n  CursorCoordinateActions\n>({\n  defaultState: {\n    coordinate: null,\n    format: 'dd',\n  },\n\n  actions: (_mapId, { set }) => ({\n    setFormat: (format: CoordinateFormatTypes) => {\n      set({ format });\n    },\n  }),\n\n  bus: (mapId, { set }) => {\n    return bus.on(MapEvents.hover, (data: MapHoverEvent) => {\n      const eventId = data.payload.id;\n\n      // Ignore hover events from other map instances\n      if (mapId !== eventId) {\n        return;\n      }\n\n      const coords = data.payload.info.coordinate;\n\n      // Update coordinate if valid, or clear if invalid\n      if (isValidCoordinate(coords)) {\n        set({ coordinate: coords as [number, number] });\n      } else {\n        set({ coordinate: null });\n      }\n    });\n  },\n});\n\n/**\n * Clear cursor coordinate state for a specific map instance.\n * This is typically not needed as cleanup happens automatically when all subscribers unmount.\n * Use this only in advanced scenarios where manual cleanup is required.\n *\n * @param instanceId - The unique identifier for the map to clear\n *\n * @example\n * ```tsx\n * // Manual cleanup (rarely needed)\n * clearCursorCoordinateState('my-map-instance');\n * ```\n */\nexport function clearCursorCoordinateState(instanceId: UniqueId): void {\n  cursorCoordinateStore.clear(instanceId);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAM,MAAM,UAAU,aAA2B;;;;;;;;AASjD,SAAS,kBAAkB,OAA6C;AACtE,QACE,MAAM,QAAQ,MAAM,IAAI,MAAM,WAAW,KAAK,MAAM,MAAM,OAAO,SAAS;;;;;;;;AAkB9E,MAAa,wBAAwB,eAGnC;CACA,cAAc;EACZ,YAAY;EACZ,QAAQ;EACT;CAED,UAAU,QAAQ,EAAE,WAAW,EAC7B,YAAY,WAAkC;AAC5C,MAAI,EAAE,QAAQ,CAAC;IAElB;CAED,MAAM,OAAO,EAAE,UAAU;AACvB,SAAO,IAAI,GAAG,UAAU,QAAQ,SAAwB;AAItD,OAAI,UAHY,KAAK,QAAQ,GAI3B;GAGF,MAAM,SAAS,KAAK,QAAQ,KAAK;AAGjC,OAAI,kBAAkB,OAAO,CAC3B,KAAI,EAAE,YAAY,QAA4B,CAAC;OAE/C,KAAI,EAAE,YAAY,MAAM,CAAC;IAE3B;;CAEL,CAAC;;;;;;;;;;;;;;AAeF,SAAgB,2BAA2B,YAA4B;AACrE,uBAAsB,MAAM,WAAW"}
+{"version":3,"file":"store.js","names":[],"sources":["../../src/cursor-coordinates/store.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Cursor Coordinates Store\n *\n * Manages cursor coordinate state for map instances using the shared store factory.\n * Subscribes to hover events from the map and stores the current cursor position.\n *\n * @example\n * ```tsx\n * import { cursorCoordinateStore } from './store';\n *\n * // Use in a component\n * function CoordinateDisplay({ mapId }) {\n *   const { state, setFormat } = cursorCoordinateStore.use(mapId);\n *   return <div>{state.coordinate ? `${state.coordinate[0]}, ${state.coordinate[1]}` : '--'}</div>;\n * }\n *\n * // Or use the selector for specific values\n * const coord = cursorCoordinateStore.useSelector(mapId, (s) => s.coordinate);\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { MapEvents } from '../deckgl/base-map/events';\nimport { createMapStore } from '../shared/create-map-store';\nimport type { UniqueId } from '@accelint/core';\nimport type { MapEventType, MapHoverEvent } from '../deckgl/base-map/types';\nimport type { CoordinateFormatTypes, CursorCoordinateState } from './types';\n\nconst bus = Broadcast.getInstance<MapEventType>();\n\n/**\n * Type guard to validate that a value is a proper coordinate tuple.\n * Checks that the value is an array with exactly two finite numbers.\n *\n * @param value - Value to validate as a coordinate\n * @returns True if value is a valid [longitude, latitude] tuple\n */\nfunction isValidCoordinate(value?: number[]): value is [number, number] {\n  return (\n    Array.isArray(value) && value.length === 2 && value.every(Number.isFinite)\n  );\n}\n\n/**\n * Actions for cursor coordinate management\n */\ntype CursorCoordinateActions = {\n  /** Set the coordinate display format */\n  setFormat: (format: CoordinateFormatTypes) => void;\n};\n\n/**\n * Cursor coordinates store\n *\n * Stores the current cursor position and display format for each map instance.\n * Automatically subscribes to hover events when first React subscriber mounts.\n */\nexport const cursorCoordinateStore = createMapStore<\n  CursorCoordinateState,\n  CursorCoordinateActions\n>({\n  defaultState: {\n    coordinate: null,\n    format: 'dd',\n  },\n\n  actions: (_mapId, { set }) => ({\n    setFormat: (format: CoordinateFormatTypes) => {\n      set({ format });\n    },\n  }),\n\n  bus: (mapId, { set }) => {\n    return bus.on(MapEvents.hover, (data: MapHoverEvent) => {\n      const eventId = data.payload.id;\n\n      // Ignore hover events from other map instances\n      if (mapId !== eventId) {\n        return;\n      }\n\n      const coords = data.payload.info.coordinate;\n\n      // Update coordinate if valid, or clear if invalid\n      if (isValidCoordinate(coords)) {\n        set({ coordinate: coords as [number, number] });\n      } else {\n        set({ coordinate: null });\n      }\n    });\n  },\n});\n\n/**\n * Clear cursor coordinate state for a specific map instance.\n * This is typically not needed as cleanup happens automatically when all subscribers unmount.\n * Use this only in advanced scenarios where manual cleanup is required.\n *\n * @param instanceId - The unique identifier for the map to clear\n * @returns void\n *\n * @example\n * ```tsx\n * // Manual cleanup (rarely needed)\n * clearCursorCoordinateState('my-map-instance');\n * ```\n */\nexport function clearCursorCoordinateState(instanceId: UniqueId): void {\n  cursorCoordinateStore.clear(instanceId);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAM,MAAM,UAAU,aAA2B;;;;;;;;AASjD,SAAS,kBAAkB,OAA6C;AACtE,QACE,MAAM,QAAQ,MAAM,IAAI,MAAM,WAAW,KAAK,MAAM,MAAM,OAAO,SAAS;;;;;;;;AAkB9E,MAAa,wBAAwB,eAGnC;CACA,cAAc;EACZ,YAAY;EACZ,QAAQ;EACT;CAED,UAAU,QAAQ,EAAE,WAAW,EAC7B,YAAY,WAAkC;AAC5C,MAAI,EAAE,QAAQ,CAAC;IAElB;CAED,MAAM,OAAO,EAAE,UAAU;AACvB,SAAO,IAAI,GAAG,UAAU,QAAQ,SAAwB;AAItD,OAAI,UAHY,KAAK,QAAQ,GAI3B;GAGF,MAAM,SAAS,KAAK,QAAQ,KAAK;AAGjC,OAAI,kBAAkB,OAAO,CAC3B,KAAI,EAAE,YAAY,QAA4B,CAAC;OAE/C,KAAI,EAAE,YAAY,MAAM,CAAC;IAE3B;;CAEL,CAAC;;;;;;;;;;;;;;;AAgBF,SAAgB,2BAA2B,YAA4B;AACrE,uBAAsB,MAAM,WAAW"}

package/dist/cursor-coordinates/use-cursor-coordinates.d.ts

@@ -29,6 +29,11 @@ import { UniqueId } from "@accelint/core";
  * @returns Object containing the formatted coordinate string, raw coordinate, format setter, and current format
  * @throws {Error} When no id is provided and hook is used outside MapProvider context
  *
+ * @remarks
+ * **UTM/MGRS Limitations:** UTM and MGRS coordinate systems are only valid between 80°S and 84°N.
+ * Coordinates outside this range (e.g., polar regions) will display the default placeholder `--, --`.
+ * Other formats (DD, DDM, DMS) work correctly at all latitudes.
+ *
  * @example
  * Basic usage:
  * ```tsx