@accelint/map-toolkit 0.3.0 → 0.4.0

package/dist/deckgl/base-map/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/deckgl/base-map/index.tsx"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/*\n * Copyright 2025 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'use client';\n\nimport 'client-only';\nimport { useEffectEvent, useEmit } from '@accelint/bus/react';\nimport { Deckgl, useDeckgl } from '@deckgl-fiber-renderer/dom';\nimport { useCallback, useId, useMemo } from 'react';\nimport { INITIAL_VIEW_STATE } from '../../maplibre/constants';\nimport { useMapLibre } from '../../maplibre/hooks/use-maplibre';\nimport { BASE_MAP_STYLE, PARAMETERS } from './constants';\nimport { MapEvents } from './events';\nimport { MapProvider } from './provider';\nimport type { UniqueId } from '@accelint/core';\nimport type { PickingInfo, ViewStateChangeParameters } from '@deck.gl/core';\nimport type { DeckglProps } from '@deckgl-fiber-renderer/types';\nimport type { IControl } from 'maplibre-gl';\nimport type { MjolnirGestureEvent, MjolnirPointerEvent } from 'mjolnir.js';\nimport type { MapClickEvent, MapHoverEvent, MapViewportEvent } from './types';\n\n/**\n * Props for the BaseMap component.\n * Extends all Deck.gl props and adds additional map-specific properties.\n */\nexport type BaseMapProps = DeckglProps & {\n  /** Optional CSS class name to apply to the map container element */\n  className?: string;\n  /**\n   * Unique identifier for this map instance (required).\n   *\n   * Used to isolate map mode state between multiple map instances (e.g., main map vs minimap).\n   * This should be a UUID generated using `uuid()` from `@accelint/core`.\n   *\n   * The same id should be passed to `useMapMode()` when accessing map mode state\n   * from components rendered outside of the BaseMap's children (i.e., as siblings).\n   */\n  id: UniqueId;\n};\n\n/**\n * A React component that provides a Deck.gl-powered base map with MapLibre GL integration.\n *\n * This component serves as the foundation for building interactive map applications with\n * support for click and hover events through a centralized event bus. It integrates\n * Deck.gl for 3D visualizations with MapLibre GL for the base map tiles.\n *\n * **Map Mode Integration**: BaseMap automatically creates a `MapProvider` internally,\n * which sets up the map mode state management for this instance.\n * - **Children**: Only Deck.gl layer components can be rendered as children. Custom Deck.gl\n *   layers can use `useMapMode()` without parameters to access context.\n * - **Siblings**: UI components (buttons, toolbars, etc.) must be rendered as siblings\n *   and pass `id` to `useMapMode(id)`.\n *\n * **Event Bus**: Click and hover events are emitted through the event bus with the `id`\n * included in the payload, allowing multiple map instances to coexist without interference.\n *\n * @param props - Component props including id (required), className, onClick, onHover, and all Deck.gl props\n * @returns A map component with Deck.gl and MapLibre GL integration\n *\n * @example\n * Basic usage with id (recommended: module-level constant):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { View } from '@deckgl-fiber-renderer/dom';\n * import { uuid } from '@accelint/core';\n *\n * // Create id at module level for stability and easy sharing\n * const MAIN_MAP_ID = uuid();\n *\n * export function MapView() {\n *   return (\n *     <BaseMap className=\"w-full h-full\" id={MAIN_MAP_ID}>\n *       <View id=\"main\" controller />\n *     </BaseMap>\n *   );\n * }\n * ```\n *\n * @example\n * With map mode and event handlers (module-level constant for sharing):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { useMapMode } from '@accelint/map-toolkit/map-mode';\n * import { uuid } from '@accelint/core';\n * import type { PickingInfo } from '@deck.gl/core';\n * import type { MjolnirGestureEvent } from 'mjolnir.js';\n *\n * // Module-level constant - stable and shareable across all components\n * const MAIN_MAP_ID = uuid();\n *\n * function Toolbar() {\n *   // Access map mode using the shared id\n *   const { mode, requestModeChange } = useMapMode(MAIN_MAP_ID);\n *   return <div>Current mode: {mode}</div>;\n * }\n *\n * export function InteractiveMap() {\n *   const handleClick = (info: PickingInfo, event: MjolnirGestureEvent) => {\n *     console.log('Clicked:', info.object);\n *   };\n *\n *   return (\n *     <div className=\"relative w-full h-full\">\n *       <BaseMap className=\"absolute inset-0\" id={MAIN_MAP_ID} onClick={handleClick}>\n *         <View id=\"main\" controller />\n *       </BaseMap>\n *       <Toolbar />\n *     </div>\n *   );\n * }\n * ```\n */\nexport function BaseMap({\n  id,\n  className,\n  children,\n  controller = true,\n  interleaved = true,\n  parameters = {},\n  useDevicePixels = false,\n  widgets: widgetsProp = [],\n  onClick,\n  onHover,\n  onViewStateChange,\n  ...rest\n}: BaseMapProps) {\n  const deckglInstance = useDeckgl();\n  const container = useId();\n\n  // Memoize MapLibre options to avoid creating new object on every render\n  const mapOptions = useMemo(\n    () => ({\n      container,\n      center: [INITIAL_VIEW_STATE.longitude, INITIAL_VIEW_STATE.latitude] as [\n        number,\n        number,\n      ],\n      zoom: INITIAL_VIEW_STATE.zoom,\n      doubleClickZoom: false,\n      dragRotate: false,\n      pitchWithRotate: false,\n      rollEnabled: false,\n      attributionControl: { compact: true },\n    }),\n    [container],\n  );\n\n  // Use the custom hook to handle MapLibre\n  useMapLibre(deckglInstance as IControl, BASE_MAP_STYLE, mapOptions);\n\n  const emitClick = useEmit<MapClickEvent>(MapEvents.click);\n  const emitHover = useEmit<MapHoverEvent>(MapEvents.hover);\n  const emitViewport = useEmit<MapViewportEvent>(MapEvents.viewport);\n\n  const handleClick = useCallback(\n    (info: PickingInfo, event: MjolnirGestureEvent) => {\n      // send full pickingInfo and event to user-defined onClick\n      onClick?.(info, event);\n\n      // omit viewport, layer, and sourceLayer (contain functions) for event bus serialization\n      // extract layerId and sourceLayerId before omission to preserve layer identification\n      const { viewport, layer, sourceLayer, ...infoRest } = info;\n      const infoObject = {\n        layerId: layer?.id,\n        sourceLayerId: sourceLayer?.id,\n        ...infoRest,\n      };\n\n      const {\n        stopImmediatePropagation,\n        stopPropagation,\n        preventDefault,\n        srcEvent,\n        rootElement,\n        target,\n        changedPointers,\n        pointers,\n        ...eventRest\n      } = event;\n\n      emitClick({\n        info: infoObject,\n        event: eventRest,\n        id,\n      });\n    },\n    [emitClick, id, onClick],\n  );\n\n  const handleHover = useCallback(\n    (info: PickingInfo, event: MjolnirPointerEvent) => {\n      // send full pickingInfo and event to user-defined onHover\n      onHover?.(info, event);\n\n      // omit viewport, layer, and sourceLayer (contain functions) for event bus serialization\n      // extract layerId and sourceLayerId before omission to preserve layer identification\n      const { viewport, layer, sourceLayer, ...infoRest } = info;\n      const infoObject = {\n        layerId: layer?.id,\n        sourceLayerId: sourceLayer?.id,\n        ...infoRest,\n      };\n\n      const {\n        stopImmediatePropagation,\n        stopPropagation,\n        preventDefault,\n        srcEvent,\n        rootElement,\n        target,\n        ...eventRest\n      } = event;\n\n      emitHover({\n        info: infoObject,\n        event: eventRest,\n        id,\n      });\n    },\n    [emitHover, id, onHover],\n  );\n\n  const handleViewStateChange = useEffectEvent(\n    (params: ViewStateChangeParameters) => {\n      onViewStateChange?.(params);\n\n      const {\n        viewId,\n        viewState: { latitude, longitude, zoom },\n      } = params;\n\n      // @ts-expect-error squirrelly deckglInstance typing\n      const viewport = deckglInstance._deck\n        .getViewports()\n        // @ts-expect-error squirrelly deckglInstance typing\n        ?.find((vp) => vp.id === viewId);\n\n      emitViewport({\n        id,\n        bounds: viewport?.getBounds(),\n        latitude,\n        longitude,\n        zoom,\n        width: viewport?.width ?? 0,\n        height: viewport?.height ?? 0,\n      });\n    },\n  );\n\n  const handleLoad = useEffectEvent(() => {\n    //--- force update viewport state once all viewports initialized ---\n    // @ts-expect-error squirrelly deckglInstance typing\n    deckglInstance._deck.getViewports().forEach((vp) => {\n      handleViewStateChange({\n        viewId: vp.id,\n        viewState: {\n          latitude: vp.latitude,\n          longitude: vp.longitude,\n          zoom: vp.zoom,\n          id: vp.id,\n          bounds: vp.getBounds(),\n          width: vp.width,\n          height: vp.height,\n        },\n      } as ViewStateChangeParameters);\n    });\n  });\n\n  return (\n    <div id={container} className={className}>\n      <MapProvider id={id}>\n        <Deckgl\n          {...rest}\n          controller={controller}\n          interleaved={interleaved}\n          useDevicePixels={useDevicePixels}\n          onClick={handleClick}\n          onHover={handleHover}\n          onLoad={handleLoad}\n          onViewStateChange={handleViewStateChange}\n          // @ts-expect-error - DeckglProps parameters type is overly strict for WebGL parameter spreading.\n          // The merged object is valid at runtime but TypeScript cannot verify all possible parameter combinations.\n          parameters={{ ...PARAMETERS, ...parameters }}\n        >\n          {children}\n        </Deckgl>\n      </MapProvider>\n    </div>\n  );\n}\n"]}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/deckgl/base-map/index.tsx"],"sourcesContent":["/*\n * Copyright 2025 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'use client';\n\nimport 'client-only';\nimport { useEffectEvent, useEmit } from '@accelint/bus/react';\nimport { Deckgl, useDeckgl } from '@deckgl-fiber-renderer/dom';\nimport { useCallback, useId, useMemo } from 'react';\nimport { getCursor } from '../../map-cursor/store';\nimport { INITIAL_VIEW_STATE } from '../../maplibre/constants';\nimport { useMapLibre } from '../../maplibre/hooks/use-maplibre';\nimport { BASE_MAP_STYLE, PARAMETERS } from './constants';\nimport { MapEvents } from './events';\nimport { MapProvider } from './provider';\nimport type { UniqueId } from '@accelint/core';\nimport type { PickingInfo, ViewStateChangeParameters } from '@deck.gl/core';\nimport type { DeckglProps } from '@deckgl-fiber-renderer/types';\nimport type { IControl } from 'maplibre-gl';\nimport type { MjolnirGestureEvent, MjolnirPointerEvent } from 'mjolnir.js';\nimport type {\n  MapClickEvent,\n  MapHoverEvent,\n  MapViewportEvent,\n  SerializablePickingInfo,\n} from './types';\n\n/**\n * Serializes PickingInfo for event bus transmission.\n * Omits viewport, layer, and sourceLayer (contain functions) but preserves layer IDs.\n */\nfunction serializePickingInfo(info: PickingInfo): SerializablePickingInfo {\n  const { viewport, layer, sourceLayer, ...infoRest } = info;\n  return {\n    layerId: layer?.id,\n    sourceLayerId: sourceLayer?.id,\n    ...infoRest,\n  };\n}\n\n/**\n * Strips non-serializable properties from MjolnirGestureEvent for event bus transmission.\n * Removes functions, DOM elements, and PointerEvent objects that cannot be cloned.\n */\nfunction serializeMjolnirEvent(\n  event: MjolnirGestureEvent,\n): Omit<\n  MjolnirGestureEvent,\n  | 'stopPropagation'\n  | 'preventDefault'\n  | 'stopImmediatePropagation'\n  | 'srcEvent'\n  | 'rootElement'\n  | 'target'\n  | 'changedPointers'\n  | 'pointers'\n>;\n/**\n * Strips non-serializable properties from MjolnirPointerEvent for event bus transmission.\n * Removes functions and DOM elements that cannot be cloned.\n */\nfunction serializeMjolnirEvent(\n  event: MjolnirPointerEvent,\n): Omit<\n  MjolnirPointerEvent,\n  | 'stopPropagation'\n  | 'preventDefault'\n  | 'stopImmediatePropagation'\n  | 'srcEvent'\n  | 'rootElement'\n  | 'target'\n>;\nfunction serializeMjolnirEvent(\n  event: MjolnirGestureEvent | MjolnirPointerEvent,\n) {\n  const {\n    stopImmediatePropagation,\n    stopPropagation,\n    preventDefault,\n    srcEvent,\n    rootElement,\n    target,\n    ...rest\n  } = event;\n\n  // Remove pointer arrays if present (only on MjolnirGestureEvent)\n  if ('changedPointers' in rest) {\n    const { changedPointers, pointers, ...gestureRest } = rest;\n    return gestureRest;\n  }\n\n  return rest;\n}\n\n/**\n * Props for the BaseMap component.\n * Extends all Deck.gl props and adds additional map-specific properties.\n */\nexport type BaseMapProps = DeckglProps & {\n  /** Optional CSS class name to apply to the map container element */\n  className?: string;\n  /**\n   * Unique identifier for this map instance (required).\n   *\n   * Used to isolate map mode state between multiple map instances (e.g., main map vs minimap).\n   * This should be a UUID generated using `uuid()` from `@accelint/core`.\n   *\n   * The same id should be passed to `useMapMode()` when accessing map mode state\n   * from components rendered outside of the BaseMap's children (i.e., as siblings).\n   */\n  id: UniqueId;\n};\n\n/**\n * A React component that provides a Deck.gl-powered base map with MapLibre GL integration.\n *\n * This component serves as the foundation for building interactive map applications with\n * support for click and hover events through a centralized event bus. It integrates\n * Deck.gl for 3D visualizations with MapLibre GL for the base map tiles.\n *\n * **Map Mode Integration**: BaseMap automatically creates a `MapProvider` internally,\n * which sets up the map mode state management for this instance.\n * - **Children**: Only Deck.gl layer components can be rendered as children. Custom Deck.gl\n *   layers can use `useMapMode()` without parameters to access context.\n * - **Siblings**: UI components (buttons, toolbars, etc.) must be rendered as siblings\n *   and pass `id` to `useMapMode(id)`.\n *\n * **Event Bus**: Click and hover events are emitted through the event bus with the `id`\n * included in the payload, allowing multiple map instances to coexist without interference.\n *\n * @param props - Component props including id (required), className, onClick, onHover, and all Deck.gl props\n * @returns A map component with Deck.gl and MapLibre GL integration\n *\n * @example\n * Basic usage with id (recommended: module-level constant):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { View } from '@deckgl-fiber-renderer/dom';\n * import { uuid } from '@accelint/core';\n *\n * // Create id at module level for stability and easy sharing\n * const MAIN_MAP_ID = uuid();\n *\n * export function MapView() {\n *   return (\n *     <BaseMap className=\"w-full h-full\" id={MAIN_MAP_ID}>\n *       <View id=\"main\" controller />\n *     </BaseMap>\n *   );\n * }\n * ```\n *\n * @example\n * With map mode and event handlers (module-level constant for sharing):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { useMapMode } from '@accelint/map-toolkit/map-mode';\n * import { uuid } from '@accelint/core';\n * import type { PickingInfo } from '@deck.gl/core';\n * import type { MjolnirGestureEvent } from 'mjolnir.js';\n *\n * // Module-level constant - stable and shareable across all components\n * const MAIN_MAP_ID = uuid();\n *\n * function Toolbar() {\n *   // Access map mode using the shared id\n *   const { mode, requestModeChange } = useMapMode(MAIN_MAP_ID);\n *   return <div>Current mode: {mode}</div>;\n * }\n *\n * export function InteractiveMap() {\n *   const handleClick = (info: PickingInfo, event: MjolnirGestureEvent) => {\n *     console.log('Clicked:', info.object);\n *   };\n *\n *   return (\n *     <div className=\"relative w-full h-full\">\n *       <BaseMap className=\"absolute inset-0\" id={MAIN_MAP_ID} onClick={handleClick}>\n *         <View id=\"main\" controller />\n *       </BaseMap>\n *       <Toolbar />\n *     </div>\n *   );\n * }\n * ```\n */\nexport function BaseMap({\n  id,\n  className,\n  children,\n  controller = true,\n  interleaved = true,\n  parameters = {},\n  useDevicePixels = false,\n  widgets: widgetsProp = [],\n  onClick,\n  onHover,\n  onViewStateChange,\n  ...rest\n}: BaseMapProps) {\n  const deckglInstance = useDeckgl();\n  const container = useId();\n\n  // Memoize MapLibre options to avoid creating new object on every render\n  const mapOptions = useMemo(\n    () => ({\n      container,\n      center: [INITIAL_VIEW_STATE.longitude, INITIAL_VIEW_STATE.latitude] as [\n        number,\n        number,\n      ],\n      zoom: INITIAL_VIEW_STATE.zoom,\n      doubleClickZoom: false,\n      dragRotate: false,\n      pitchWithRotate: false,\n      rollEnabled: false,\n      attributionControl: { compact: true },\n    }),\n    [container],\n  );\n\n  // Use the custom hook to handle MapLibre\n  useMapLibre(deckglInstance as IControl, BASE_MAP_STYLE, mapOptions);\n\n  const emitClick = useEmit<MapClickEvent>(MapEvents.click);\n  const emitHover = useEmit<MapHoverEvent>(MapEvents.hover);\n  const emitViewport = useEmit<MapViewportEvent>(MapEvents.viewport);\n\n  const handleClick = useCallback(\n    (info: PickingInfo, event: MjolnirGestureEvent) => {\n      // send full pickingInfo and event to user-defined onClick\n      onClick?.(info, event);\n\n      emitClick({\n        info: serializePickingInfo(info),\n        event: serializeMjolnirEvent(event),\n        id,\n      });\n    },\n    [emitClick, id, onClick],\n  );\n\n  const handleHover = useCallback(\n    (info: PickingInfo, event: MjolnirPointerEvent) => {\n      // send full pickingInfo and event to user-defined onHover\n      onHover?.(info, event);\n\n      emitHover({\n        info: serializePickingInfo(info),\n        event: serializeMjolnirEvent(event),\n        id,\n      });\n    },\n    [emitHover, id, onHover],\n  );\n\n  const handleGetCursor = useCallback(() => {\n    return getCursor(id);\n  }, [id]);\n\n  const handleViewStateChange = useEffectEvent(\n    (params: ViewStateChangeParameters) => {\n      onViewStateChange?.(params);\n\n      const {\n        viewId,\n        viewState: { latitude, longitude, zoom },\n      } = params;\n\n      // @ts-expect-error squirrelly deckglInstance typing\n      const viewport = deckglInstance._deck\n        .getViewports()\n        // @ts-expect-error squirrelly deckglInstance typing\n        ?.find((vp) => vp.id === viewId);\n\n      emitViewport({\n        id,\n        bounds: viewport?.getBounds(),\n        latitude,\n        longitude,\n        zoom,\n        width: viewport?.width ?? 0,\n        height: viewport?.height ?? 0,\n      });\n    },\n  );\n\n  const handleLoad = useEffectEvent(() => {\n    //--- force update viewport state once all viewports initialized ---\n    // @ts-expect-error squirrelly deckglInstance typing\n    deckglInstance._deck.getViewports().forEach((vp) => {\n      handleViewStateChange({\n        viewId: vp.id,\n        viewState: {\n          latitude: vp.latitude,\n          longitude: vp.longitude,\n          zoom: vp.zoom,\n          id: vp.id,\n          bounds: vp.getBounds(),\n          width: vp.width,\n          height: vp.height,\n        },\n      } as ViewStateChangeParameters);\n    });\n  });\n\n  return (\n    <div id={container} className={className}>\n      <MapProvider id={id}>\n        <Deckgl\n          {...rest}\n          controller={controller}\n          interleaved={interleaved}\n          useDevicePixels={useDevicePixels}\n          onClick={handleClick}\n          onHover={handleHover}\n          onLoad={handleLoad}\n          onViewStateChange={handleViewStateChange}\n          getCursor={handleGetCursor}\n          // @ts-expect-error - DeckglProps parameters type is overly strict for WebGL parameter spreading.\n          // The merged object is valid at runtime but TypeScript cannot verify all possible parameter combinations.\n          parameters={{ ...PARAMETERS, ...parameters }}\n        >\n          {children}\n        </Deckgl>\n      </MapProvider>\n    </div>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAS,qBAAqB,MAA4C;CACxE,MAAM,EAAE,UAAU,OAAO,aAAa,GAAG,aAAa;AACtD,QAAO;EACL,SAAS,OAAO;EAChB,eAAe,aAAa;EAC5B,GAAG;EACJ;;AAmCH,SAAS,sBACP,OACA;CACA,MAAM,EACJ,0BACA,iBACA,gBACA,UACA,aACA,QACA,GAAG,SACD;AAGJ,KAAI,qBAAqB,MAAM;EAC7B,MAAM,EAAE,iBAAiB,UAAU,GAAG,gBAAgB;AACtD,SAAO;;AAGT,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+FT,SAAgB,QAAQ,EACtB,IACA,WACA,UACA,aAAa,MACb,cAAc,MACd,aAAa,EAAE,EACf,kBAAkB,OAClB,SAAS,cAAc,EAAE,EACzB,SACA,SACA,mBACA,GAAG,QACY;CACf,MAAM,iBAAiB,WAAW;CAClC,MAAM,YAAY,OAAO;AAqBzB,aAAY,gBAA4B,gBAlBrB,eACV;EACL;EACA,QAAQ,CAAC,mBAAmB,WAAW,mBAAmB,SAAS;EAInE,MAAM,mBAAmB;EACzB,iBAAiB;EACjB,YAAY;EACZ,iBAAiB;EACjB,aAAa;EACb,oBAAoB,EAAE,SAAS,MAAM;EACtC,GACD,CAAC,UAAU,CACZ,CAGkE;CAEnE,MAAM,YAAY,QAAuB,UAAU,MAAM;CACzD,MAAM,YAAY,QAAuB,UAAU,MAAM;CACzD,MAAM,eAAe,QAA0B,UAAU,SAAS;CAElE,MAAM,cAAc,aACjB,MAAmB,UAA+B;AAEjD,YAAU,MAAM,MAAM;AAEtB,YAAU;GACR,MAAM,qBAAqB,KAAK;GAChC,OAAO,sBAAsB,MAAM;GACnC;GACD,CAAC;IAEJ;EAAC;EAAW;EAAI;EAAQ,CACzB;CAED,MAAM,cAAc,aACjB,MAAmB,UAA+B;AAEjD,YAAU,MAAM,MAAM;AAEtB,YAAU;GACR,MAAM,qBAAqB,KAAK;GAChC,OAAO,sBAAsB,MAAM;GACnC;GACD,CAAC;IAEJ;EAAC;EAAW;EAAI;EAAQ,CACzB;CAED,MAAM,kBAAkB,kBAAkB;AACxC,SAAO,UAAU,GAAG;IACnB,CAAC,GAAG,CAAC;CAER,MAAM,wBAAwB,gBAC3B,WAAsC;AACrC,sBAAoB,OAAO;EAE3B,MAAM,EACJ,QACA,WAAW,EAAE,UAAU,WAAW,WAChC;EAGJ,MAAM,WAAW,eAAe,MAC7B,cAAc,EAEb,MAAM,OAAO,GAAG,OAAO,OAAO;AAElC,eAAa;GACX;GACA,QAAQ,UAAU,WAAW;GAC7B;GACA;GACA;GACA,OAAO,UAAU,SAAS;GAC1B,QAAQ,UAAU,UAAU;GAC7B,CAAC;GAEL;CAED,MAAM,aAAa,qBAAqB;AAGtC,iBAAe,MAAM,cAAc,CAAC,SAAS,OAAO;AAClD,yBAAsB;IACpB,QAAQ,GAAG;IACX,WAAW;KACT,UAAU,GAAG;KACb,WAAW,GAAG;KACd,MAAM,GAAG;KACT,IAAI,GAAG;KACP,QAAQ,GAAG,WAAW;KACtB,OAAO,GAAG;KACV,QAAQ,GAAG;KACZ;IACF,CAA8B;IAC/B;GACF;AAEF,QACE,oBAAC;EAAI,IAAI;EAAsB;YAC7B,oBAAC;GAAgB;aACf,oBAAC;IACC,GAAI;IACQ;IACC;IACI;IACjB,SAAS;IACT,SAAS;IACT,QAAQ;IACR,mBAAmB;IACnB,WAAW;IAGX,YAAY;KAAE,GAAG;KAAY,GAAG;KAAY;IAE3C;KACM;IACG;GACV"}

package/dist/deckgl/base-map/provider.d.ts

@@ -1,41 +1,53 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { UniqueId } from '@accelint/core';
+/*
+ * 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.
+ */
 
+import { ReactNode } from "react";
+import { UniqueId } from "@accelint/core";
+import * as react_jsx_runtime1 from "react/jsx-runtime";
+
+//#region src/deckgl/base-map/provider.d.ts
 /**
  * React context for map ID.
  * Use the `useMapMode` hook to access the map mode state.
  */
-declare const MapContext: react.Context<UniqueId | null>;
+declare const MapContext: React.Context<UniqueId | null>;
 /**
  * Props for the MapProvider component.
  */
 type MapProviderProps = {
-    /** Child components that will have access to map mode context */
-    children: ReactNode;
-    /**
-     * Unique identifier for this map instance.
-     *
-     * Used to isolate mode changes between different map instances (e.g., main map vs minimap).
-     * This is required and should be provided by the parent component (typically BaseMap).
-     *
-     * @example
-     * ```tsx
-     * // Multiple independent map instances
-     * const mainMapId = uuid();
-     * const minimapId = uuid();
-     *
-     * <MapProvider id={mainMapId}>
-     *  // Map layers and components
-     * </MapProvider>
-     *
-     * <MapProvider id={minimapId}>
-     *  // Minimap layers and components
-     * </MapProvider>
-     * ```
-     */
-    id: UniqueId;
+  /** Child components that will have access to map mode context */
+  children: ReactNode;
+  /**
+   * Unique identifier for this map instance.
+   *
+   * Used to isolate mode changes between different map instances (e.g., main map vs minimap).
+   * This is required and should be provided by the parent component (typically BaseMap).
+   *
+   * @example
+   * ```tsx
+   * // Multiple independent map instances
+   * const mainMapId = uuid();
+   * const minimapId = uuid();
+   *
+   * <MapProvider id={mainMapId}>
+   *  // Map layers and components
+   * </MapProvider>
+   *
+   * <MapProvider id={minimapId}>
+   *  // Minimap layers and components
+   * </MapProvider>
+   * ```
+   */
+  id: UniqueId;
 };
 /**
  * Provider component for managing map modes with ownership and authorization.
@@ -124,6 +136,10 @@ type MapProviderProps = {
  * });
  * ```
  */
-declare function MapProvider({ children, id }: MapProviderProps): react_jsx_runtime.JSX.Element;
-
-export { MapContext, MapProvider, type MapProviderProps };
+declare function MapProvider({
+  children,
+  id
+}: MapProviderProps): react_jsx_runtime1.JSX.Element;
+//#endregion
+export { MapContext, MapProvider, MapProviderProps };
+//# sourceMappingURL=provider.d.ts.map

package/dist/deckgl/base-map/provider.js

@@ -1,18 +1,129 @@
-import { jsx } from 'react/jsx-runtime';
-import 'client-only';
-import { createContext, useEffect } from 'react';
-import { clearMapModeState } from '../../map-mode/store.js';
+/*
+ * 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.
+ */
 
+
+'use client';
+
+import { clearMapModeState } from "../../map-mode/store.js";
+import { clearCursorState } from "../../map-cursor/store.js";
+import { createContext, useEffect } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/deckgl/base-map/provider.tsx
+/**
+* React context for map ID.
+* Use the `useMapMode` hook to access the map mode state.
+*/
 const MapContext = createContext(null);
+/**
+* Provider component for managing map modes with ownership and authorization.
+*
+* **Note**: This provider is used internally by `BaseMap` and should not be used directly.
+* Consumers should pass the `id` prop to `BaseMap`, which will create this provider automatically.
+*
+* This component uses a hybrid architecture combining React Context (for map instance identity)
+* with module-level state management (for map mode state). The provider:
+* - Provides a unique `id` via Context
+* - Cleans up map mode state when unmounted
+* - Allows components to subscribe to mode changes via `useMapMode` hook (which uses `useSyncExternalStore`)
+*
+* The module-level state management system implements a state machine for map modes where
+* components can request mode changes with ownership. When a mode is owned by a component,
+* other components must request authorization to change to a different mode. The system handles:
+*
+* - Automatic mode changes when no ownership conflicts exist
+* - Authorization flow when switching between owned modes
+* - Per-mode ownership tracking that persists throughout the session
+* - Pending request management (one pending request per requester)
+* - Auto-acceptance of first pending request when mode owner returns to default
+* - Auto-rejection of other pending requests when one is approved
+* - Event emission through a centralized event bus
+* - Instance isolation for multiple map scenarios (main map + minimap)
+* - Always initializes in 'default' mode
+*
+* ## Instance Isolation
+*
+* Each MapProvider instance operates independently. Mode changes in one instance
+* do not affect other instances, even when multiple maps are rendered on the same page.
+* This enables scenarios like:
+* - Main map in "drawing" mode while minimap stays in "view" mode
+* - Multiple independent map views with different interaction modes
+*
+* Events are scoped to specific instances using the `id` prop. The event bus
+* filters events to ensure each provider only responds to events for its own instance.
+*
+* ## Pending Request Behavior
+*
+* - Pending requests are stored by requester ID (not mode owner)
+* - Each requester can have only one pending request at a time
+* - New requests from the same requester auto-replace previous requests
+* - Pending requests persist when mode owner switches between their own modes
+* - When any request is approved, all other pending requests are auto-rejected
+* - When mode owner returns to default mode:
+*   - If first pending request is for default mode, all pending requests are rejected (already in requested mode)
+*   - If first pending request is for a different mode, that request is auto-approved and others are rejected
+*
+* ## Instance ID Stability and Lifecycle
+*
+* The provider's cleanup mechanism (via `useEffect`) ensures proper state management:
+* - Map mode state is cleaned up when the provider unmounts
+* - Changing the `id` prop will trigger cleanup of the old state via the effect dependency
+* - State is lazily initialized on first subscription (no manual creation needed)
+*
+* While the `id` prop should typically remain stable (created as a module-level constant
+* or with `useState`), changing it will work correctly due to the cleanup mechanism.
+*
+* @param props - Provider props including children and required id
+* @returns Provider component that wraps children with map instance identity context
+*
+* @example
+* Internal usage within BaseMap:
+* ```tsx
+* // BaseMap automatically creates the provider
+* function BaseMap({ id, children, ...props }: BaseMapProps) {
+*   return (
+*     <div>
+*       <MapProvider id={id}>
+*         <Deckgl {...props}>
+*           {children}
+*         </Deckgl>
+*       </MapProvider>
+*     </div>
+*   );
+* }
+* ```
+*
+* @example
+* With authorization handling - use id in event payloads:
+* ```tsx
+* useOn(MapModeEvents.changeAuthorization, (event) => {
+*   const { authId, id } = event.payload;
+*   emitDecision({ authId, approved: true, owner: 'tool', id });
+* });
+* ```
+*/
 function MapProvider({ children, id }) {
-  useEffect(() => {
-    return () => {
-      clearMapModeState(id);
-    };
-  }, [id]);
-  return /* @__PURE__ */ jsx(MapContext.Provider, { value: id, children });
+	useEffect(() => {
+		return () => {
+			clearMapModeState(id);
+			clearCursorState(id);
+		};
+	}, [id]);
+	return /* @__PURE__ */ jsx(MapContext.Provider, {
+		value: id,
+		children
+	});
 }
 
+//#endregion
 export { MapContext, MapProvider };
-//# sourceMappingURL=provider.js.map
 //# sourceMappingURL=provider.js.map

package/dist/deckgl/base-map/provider.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/deckgl/base-map/provider.tsx"],"names":[],"mappings":";;;;;AAuBO,MAAM,UAAA,GAAa,cAA+B,IAAI;AAuHtD,SAAS,WAAA,CAAY,EAAE,QAAA,EAAU,EAAA,EAAG,EAAqB;AAG9D,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,OAAO,MAAM;AACX,MAAA,iBAAA,CAAkB,EAAE,CAAA;AAAA,IACtB,CAAA;AAAA,EACF,CAAA,EAAG,CAAC,EAAE,CAAC,CAAA;AAEP,EAAA,2BAAQ,UAAA,CAAW,QAAA,EAAX,EAAoB,KAAA,EAAO,IAAK,QAAA,EAAS,CAAA;AACnD","file":"provider.js","sourcesContent":["/*\n * Copyright 2025 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'use client';\n\nimport 'client-only';\nimport { createContext, type ReactNode, useEffect } from 'react';\nimport { clearMapModeState } from '../../map-mode/store';\nimport type { UniqueId } from '@accelint/core';\n\n/**\n * React context for map ID.\n * Use the `useMapMode` hook to access the map mode state.\n */\nexport const MapContext = createContext<UniqueId | null>(null);\n\n/**\n * Props for the MapProvider component.\n */\nexport type MapProviderProps = {\n  /** Child components that will have access to map mode context */\n  children: ReactNode;\n  /**\n   * Unique identifier for this map instance.\n   *\n   * Used to isolate mode changes between different map instances (e.g., main map vs minimap).\n   * This is required and should be provided by the parent component (typically BaseMap).\n   *\n   * @example\n   * ```tsx\n   * // Multiple independent map instances\n   * const mainMapId = uuid();\n   * const minimapId = uuid();\n   *\n   * <MapProvider id={mainMapId}>\n   *  // Map layers and components\n   * </MapProvider>\n   *\n   * <MapProvider id={minimapId}>\n   *  // Minimap layers and components\n   * </MapProvider>\n   * ```\n   */\n  id: UniqueId;\n};\n\n/**\n * Provider component for managing map modes with ownership and authorization.\n *\n * **Note**: This provider is used internally by `BaseMap` and should not be used directly.\n * Consumers should pass the `id` prop to `BaseMap`, which will create this provider automatically.\n *\n * This component uses a hybrid architecture combining React Context (for map instance identity)\n * with module-level state management (for map mode state). The provider:\n * - Provides a unique `id` via Context\n * - Cleans up map mode state when unmounted\n * - Allows components to subscribe to mode changes via `useMapMode` hook (which uses `useSyncExternalStore`)\n *\n * The module-level state management system implements a state machine for map modes where\n * components can request mode changes with ownership. When a mode is owned by a component,\n * other components must request authorization to change to a different mode. The system handles:\n *\n * - Automatic mode changes when no ownership conflicts exist\n * - Authorization flow when switching between owned modes\n * - Per-mode ownership tracking that persists throughout the session\n * - Pending request management (one pending request per requester)\n * - Auto-acceptance of first pending request when mode owner returns to default\n * - Auto-rejection of other pending requests when one is approved\n * - Event emission through a centralized event bus\n * - Instance isolation for multiple map scenarios (main map + minimap)\n * - Always initializes in 'default' mode\n *\n * ## Instance Isolation\n *\n * Each MapProvider instance operates independently. Mode changes in one instance\n * do not affect other instances, even when multiple maps are rendered on the same page.\n * This enables scenarios like:\n * - Main map in \"drawing\" mode while minimap stays in \"view\" mode\n * - Multiple independent map views with different interaction modes\n *\n * Events are scoped to specific instances using the `id` prop. The event bus\n * filters events to ensure each provider only responds to events for its own instance.\n *\n * ## Pending Request Behavior\n *\n * - Pending requests are stored by requester ID (not mode owner)\n * - Each requester can have only one pending request at a time\n * - New requests from the same requester auto-replace previous requests\n * - Pending requests persist when mode owner switches between their own modes\n * - When any request is approved, all other pending requests are auto-rejected\n * - When mode owner returns to default mode:\n *   - If first pending request is for default mode, all pending requests are rejected (already in requested mode)\n *   - If first pending request is for a different mode, that request is auto-approved and others are rejected\n *\n * ## Instance ID Stability and Lifecycle\n *\n * The provider's cleanup mechanism (via `useEffect`) ensures proper state management:\n * - Map mode state is cleaned up when the provider unmounts\n * - Changing the `id` prop will trigger cleanup of the old state via the effect dependency\n * - State is lazily initialized on first subscription (no manual creation needed)\n *\n * While the `id` prop should typically remain stable (created as a module-level constant\n * or with `useState`), changing it will work correctly due to the cleanup mechanism.\n *\n * @param props - Provider props including children and required id\n * @returns Provider component that wraps children with map instance identity context\n *\n * @example\n * Internal usage within BaseMap:\n * ```tsx\n * // BaseMap automatically creates the provider\n * function BaseMap({ id, children, ...props }: BaseMapProps) {\n *   return (\n *     <div>\n *       <MapProvider id={id}>\n *         <Deckgl {...props}>\n *           {children}\n *         </Deckgl>\n *       </MapProvider>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * With authorization handling - use id in event payloads:\n * ```tsx\n * useOn(MapModeEvents.changeAuthorization, (event) => {\n *   const { authId, id } = event.payload;\n *   emitDecision({ authId, approved: true, owner: 'tool', id });\n * });\n * ```\n */\nexport function MapProvider({ children, id }: MapProviderProps) {\n  // Cleanup when component unmounts\n  // State is created automatically on first subscription in useMapMode\n  useEffect(() => {\n    return () => {\n      clearMapModeState(id);\n    };\n  }, [id]);\n\n  return <MapContext.Provider value={id}>{children}</MapContext.Provider>;\n}\n"]}
+{"version":3,"file":"provider.js","names":[],"sources":["../../../src/deckgl/base-map/provider.tsx"],"sourcesContent":["/*\n * Copyright 2025 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'use client';\n\nimport 'client-only';\nimport { createContext, type ReactNode, useEffect } from 'react';\nimport { clearCursorState } from '../../map-cursor/store';\nimport { clearMapModeState } from '../../map-mode/store';\nimport type { UniqueId } from '@accelint/core';\n\n/**\n * React context for map ID.\n * Use the `useMapMode` hook to access the map mode state.\n */\nexport const MapContext = createContext<UniqueId | null>(null);\n\n/**\n * Props for the MapProvider component.\n */\nexport type MapProviderProps = {\n  /** Child components that will have access to map mode context */\n  children: ReactNode;\n  /**\n   * Unique identifier for this map instance.\n   *\n   * Used to isolate mode changes between different map instances (e.g., main map vs minimap).\n   * This is required and should be provided by the parent component (typically BaseMap).\n   *\n   * @example\n   * ```tsx\n   * // Multiple independent map instances\n   * const mainMapId = uuid();\n   * const minimapId = uuid();\n   *\n   * <MapProvider id={mainMapId}>\n   *  // Map layers and components\n   * </MapProvider>\n   *\n   * <MapProvider id={minimapId}>\n   *  // Minimap layers and components\n   * </MapProvider>\n   * ```\n   */\n  id: UniqueId;\n};\n\n/**\n * Provider component for managing map modes with ownership and authorization.\n *\n * **Note**: This provider is used internally by `BaseMap` and should not be used directly.\n * Consumers should pass the `id` prop to `BaseMap`, which will create this provider automatically.\n *\n * This component uses a hybrid architecture combining React Context (for map instance identity)\n * with module-level state management (for map mode state). The provider:\n * - Provides a unique `id` via Context\n * - Cleans up map mode state when unmounted\n * - Allows components to subscribe to mode changes via `useMapMode` hook (which uses `useSyncExternalStore`)\n *\n * The module-level state management system implements a state machine for map modes where\n * components can request mode changes with ownership. When a mode is owned by a component,\n * other components must request authorization to change to a different mode. The system handles:\n *\n * - Automatic mode changes when no ownership conflicts exist\n * - Authorization flow when switching between owned modes\n * - Per-mode ownership tracking that persists throughout the session\n * - Pending request management (one pending request per requester)\n * - Auto-acceptance of first pending request when mode owner returns to default\n * - Auto-rejection of other pending requests when one is approved\n * - Event emission through a centralized event bus\n * - Instance isolation for multiple map scenarios (main map + minimap)\n * - Always initializes in 'default' mode\n *\n * ## Instance Isolation\n *\n * Each MapProvider instance operates independently. Mode changes in one instance\n * do not affect other instances, even when multiple maps are rendered on the same page.\n * This enables scenarios like:\n * - Main map in \"drawing\" mode while minimap stays in \"view\" mode\n * - Multiple independent map views with different interaction modes\n *\n * Events are scoped to specific instances using the `id` prop. The event bus\n * filters events to ensure each provider only responds to events for its own instance.\n *\n * ## Pending Request Behavior\n *\n * - Pending requests are stored by requester ID (not mode owner)\n * - Each requester can have only one pending request at a time\n * - New requests from the same requester auto-replace previous requests\n * - Pending requests persist when mode owner switches between their own modes\n * - When any request is approved, all other pending requests are auto-rejected\n * - When mode owner returns to default mode:\n *   - If first pending request is for default mode, all pending requests are rejected (already in requested mode)\n *   - If first pending request is for a different mode, that request is auto-approved and others are rejected\n *\n * ## Instance ID Stability and Lifecycle\n *\n * The provider's cleanup mechanism (via `useEffect`) ensures proper state management:\n * - Map mode state is cleaned up when the provider unmounts\n * - Changing the `id` prop will trigger cleanup of the old state via the effect dependency\n * - State is lazily initialized on first subscription (no manual creation needed)\n *\n * While the `id` prop should typically remain stable (created as a module-level constant\n * or with `useState`), changing it will work correctly due to the cleanup mechanism.\n *\n * @param props - Provider props including children and required id\n * @returns Provider component that wraps children with map instance identity context\n *\n * @example\n * Internal usage within BaseMap:\n * ```tsx\n * // BaseMap automatically creates the provider\n * function BaseMap({ id, children, ...props }: BaseMapProps) {\n *   return (\n *     <div>\n *       <MapProvider id={id}>\n *         <Deckgl {...props}>\n *           {children}\n *         </Deckgl>\n *       </MapProvider>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * With authorization handling - use id in event payloads:\n * ```tsx\n * useOn(MapModeEvents.changeAuthorization, (event) => {\n *   const { authId, id } = event.payload;\n *   emitDecision({ authId, approved: true, owner: 'tool', id });\n * });\n * ```\n */\nexport function MapProvider({ children, id }: MapProviderProps) {\n  // Cleanup when component unmounts\n  // State is created automatically on first subscription in useMapMode/useMapCursor\n  useEffect(() => {\n    return () => {\n      clearMapModeState(id);\n      clearCursorState(id);\n    };\n  }, [id]);\n\n  return <MapContext.Provider value={id}>{children}</MapContext.Provider>;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,MAAa,aAAa,cAA+B,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuH9D,SAAgB,YAAY,EAAE,UAAU,MAAwB;AAG9D,iBAAgB;AACd,eAAa;AACX,qBAAkB,GAAG;AACrB,oBAAiB,GAAG;;IAErB,CAAC,GAAG,CAAC;AAER,QAAO,oBAAC,WAAW;EAAS,OAAO;EAAK;GAA+B"}

package/dist/deckgl/base-map/types.d.ts

@@ -1,19 +1,32 @@
-import { Payload } from '@accelint/bus';
-import { UniqueId } from '@accelint/core';
-import { PickingInfo } from '@deck.gl/core';
-import { MjolnirGestureEvent, MjolnirPointerEvent } from 'mjolnir.js';
-import { MapEvents } from './events.js';
+/*
+ * 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.
+ */
+
+import { MapEvents } from "./events.js";
+import { Payload } from "@accelint/bus";
+import { UniqueId } from "@accelint/core";
+import { PickingInfo } from "@deck.gl/core";
+import { MjolnirGestureEvent, MjolnirPointerEvent } from "mjolnir.js";
 
+//#region src/deckgl/base-map/types.d.ts
 /**
  * PickingInfo modified for serialization through the event bus.
  * Omits viewport, layer, and sourceLayer (which contain non-serializable functions),
  * and adds layerId and sourceLayerId extracted from the original layer objects.
  */
-type NonFuncPickingInfo = Omit<PickingInfo, 'viewport' | 'layer' | 'sourceLayer'> & {
-    /** ID of the picked layer (extracted from layer.id before omission) */
-    layerId?: NonNullable<PickingInfo['layer']>['id'];
-    /** ID of the source layer if applicable (extracted from sourceLayer.id before omission) */
-    sourceLayerId?: NonNullable<PickingInfo['sourceLayer']>['id'];
+type SerializablePickingInfo = Omit<PickingInfo, 'viewport' | 'layer' | 'sourceLayer'> & {
+  /** ID of the picked layer (extracted from layer.id before omission) */
+  layerId?: NonNullable<PickingInfo['layer']>['id'];
+  /** ID of the source layer if applicable (extracted from sourceLayer.id before omission) */
+  sourceLayerId?: NonNullable<PickingInfo['sourceLayer']>['id'];
 };
 /**
  * MjolnirGestureEvent without function properties and non-serializable objects.
@@ -30,41 +43,37 @@ type NonFuncMjolnirPointerEvent = Omit<MjolnirPointerEvent, 'stopPropagation' |
  * Contains picking information about what was clicked and the gesture event details.
  */
 type MapClickPayload = {
-    /** Information about the picked object and its properties */
-    info: NonFuncPickingInfo;
-    /** The gesture event that triggered the click */
-    event: NonFuncMjolnirGestureEvent;
-    /** The map instance the event occurred within */
-    id: UniqueId;
+  /** Information about the picked object and its properties */
+  info: SerializablePickingInfo;
+  /** The gesture event that triggered the click */
+  event: NonFuncMjolnirGestureEvent;
+  /** The map instance the event occurred within */
+  id: UniqueId;
 };
 /**
  * Payload for map hover events emitted through the event bus.
  * Contains picking information about what is being hovered and the pointer event details.
  */
 type MapHoverPayload = {
-    /** Information about the picked object and its properties */
-    info: NonFuncPickingInfo;
-    /** The pointer event that triggered the hover */
-    event: NonFuncMjolnirPointerEvent;
-    /** The map instance the event occurred within */
-    id: UniqueId;
+  /** Information about the picked object and its properties */
+  info: SerializablePickingInfo;
+  /** The pointer event that triggered the hover */
+  event: NonFuncMjolnirPointerEvent;
+  /** The map instance the event occurred within */
+  id: UniqueId;
 };
-type Bounds = [
-    minLon: number,
-    minLat: number,
-    maxLon: number,
-    maxLat: number
-];
+type Bounds = [minLon: number, minLat: number, maxLon: number, maxLat: number];
 type MapViewportPayload = {
-    bounds: Bounds;
-    latitude: number;
-    longitude: number;
-    zoom: number;
-    /** Viewport width in pixels */
-    width: number;
-    /** Viewport height in pixels */
-    height: number;
-    id: UniqueId;
+  /** Viewport bounds, undefined if viewport not yet initialized */
+  bounds?: Bounds;
+  latitude: number;
+  longitude: number;
+  zoom: number;
+  /** Viewport width in pixels */
+  width: number;
+  /** Viewport height in pixels */
+  height: number;
+  id: UniqueId;
 };
 /**
  * Type for map click events in the event bus.
@@ -78,5 +87,6 @@ type MapClickEvent = Payload<typeof MapEvents.click, MapClickPayload>;
 type MapHoverEvent = Payload<typeof MapEvents.hover, MapHoverPayload>;
 type MapViewportEvent = Payload<typeof MapEvents.viewport, MapViewportPayload>;
 type MapEventType = MapClickEvent | MapHoverEvent | MapViewportEvent;
-
-export type { Bounds, MapClickEvent, MapClickPayload, MapEventType, MapHoverEvent, MapHoverPayload, MapViewportEvent, MapViewportPayload };
+//#endregion
+export { Bounds, MapClickEvent, MapClickPayload, MapEventType, MapHoverEvent, MapHoverPayload, MapViewportEvent, MapViewportPayload, SerializablePickingInfo };
+//# sourceMappingURL=types.d.ts.map

package/dist/deckgl/base-map/types.js

@@ -1,3 +1,12 @@
+/*
+ * 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.
+ */
 
-//# sourceMappingURL=types.js.map
-//# sourceMappingURL=types.js.map

package/dist/deckgl/index.d.ts

@@ -1,13 +1,18 @@
-export { BaseMap, BaseMapProps } from './base-map/index.js';
-export { BASE_MAP_STYLE, PARAMETERS } from './base-map/constants.js';
-export { MapEvents, MapEventsNamespace } from './base-map/events.js';
-export { SymbolLayer, SymbolLayerProps } from './symbol-layer/index.js';
-export { MapClickEvent, MapClickPayload, MapEventType, MapHoverEvent, MapHoverPayload } from './base-map/types.js';
-import 'react/jsx-runtime';
-import '@accelint/core';
-import '@deckgl-fiber-renderer/types';
-import '@deck.gl/layers';
-import 'milsymbol';
-import '@deck.gl/core';
-import '@accelint/bus';
-import 'mjolnir.js';
+/*
+ * 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.
+ */
+
+import { BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
+import { MapEvents, MapEventsNamespace } from "./base-map/events.js";
+import { BaseMap, BaseMapProps } from "./base-map/index.js";
+import { MapClickEvent, MapClickPayload, MapEventType, MapHoverEvent, MapHoverPayload } from "./base-map/types.js";
+import { SymbolLayer, SymbolLayerProps } from "./symbol-layer/index.js";
+export { BASE_MAP_STYLE, BaseMap, type BaseMapProps, type MapClickEvent, type MapClickPayload, type MapEventType, MapEvents, MapEventsNamespace, type MapHoverEvent, type MapHoverPayload, PARAMETERS, SymbolLayer, type SymbolLayerProps };

package/dist/deckgl/index.js

@@ -1,6 +1,19 @@
-export { BaseMap } from './base-map/index.js';
-export { BASE_MAP_STYLE, PARAMETERS } from './base-map/constants.js';
-export { MapEvents, MapEventsNamespace } from './base-map/events.js';
-export { SymbolLayer } from './symbol-layer/index.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+/*
+ * 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.
+ */
+
+
+import { MapEvents, MapEventsNamespace } from "./base-map/events.js";
+import { BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
+import { BaseMap } from "./base-map/index.js";
+import { SymbolLayer } from "./symbol-layer/index.js";
+
+export { BASE_MAP_STYLE, BaseMap, MapEvents, MapEventsNamespace, PARAMETERS, SymbolLayer };

package/dist/deckgl/symbol-layer/fiber.d.ts

@@ -1,14 +1,25 @@
-import { SymbolLayerProps } from './index.js';
-import '@deck.gl/layers';
-import 'milsymbol';
-import '@deck.gl/core';
+/*
+ * 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.
+ */
 
+import { SymbolLayerProps } from "./index.js";
+
+//#region src/deckgl/symbol-layer/fiber.d.ts
 declare global {
-    namespace React {
-        namespace JSX {
-            interface IntrinsicElements {
-                symbolLayer: SymbolLayerProps;
-            }
-        }
+  namespace React {
+    namespace JSX {
+      interface IntrinsicElements {
+        symbolLayer: SymbolLayerProps;
+      }
     }
+  }
 }
+//# sourceMappingURL=fiber.d.ts.map

package/dist/deckgl/symbol-layer/fiber.js

@@ -1,6 +1,21 @@
-import { extend } from '@deckgl-fiber-renderer/dom';
-import { SymbolLayer } from './index.js';
+/*
+ * 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.
+ */
 
+
+import { SymbolLayer } from "./index.js";
+import { extend } from "@deckgl-fiber-renderer/dom";
+
+//#region src/deckgl/symbol-layer/fiber.ts
 extend({ SymbolLayer });
-//# sourceMappingURL=fiber.js.map
+
+//#endregion
 //# sourceMappingURL=fiber.js.map

package/dist/deckgl/symbol-layer/fiber.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/deckgl/symbol-layer/fiber.ts"],"names":[],"mappings":";;;AAeA,MAAA,CAAO,EAAE,aAAa,CAAA","file":"fiber.js","sourcesContent":["/*\n * Copyright 2025 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\nimport { extend } from '@deckgl-fiber-renderer/dom';\nimport { SymbolLayer, type SymbolLayerProps } from './index';\n\nextend({ SymbolLayer });\n\ndeclare global {\n  namespace React {\n    // biome-ignore lint/style/useNamingConvention: Built-in React namespace.\n    namespace JSX {\n      interface IntrinsicElements {\n        symbolLayer: SymbolLayerProps;\n      }\n    }\n  }\n}\n"]}
+{"version":3,"file":"fiber.js","names":[],"sources":["../../../src/deckgl/symbol-layer/fiber.ts"],"sourcesContent":["/*\n * Copyright 2025 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\nimport { extend } from '@deckgl-fiber-renderer/dom';\nimport { SymbolLayer, type SymbolLayerProps } from './index';\n\nextend({ SymbolLayer });\n\ndeclare global {\n  namespace React {\n    // biome-ignore lint/style/useNamingConvention: Built-in React namespace.\n    namespace JSX {\n      interface IntrinsicElements {\n        symbolLayer: SymbolLayerProps;\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAeA,OAAO,EAAE,aAAa,CAAC"}