@accelint/map-toolkit 1.5.0 → 3.0.0

package/dist/deckgl/extensions/coffin-corner/use-coffin-corner.js

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2026 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 { coffinCornerStore } from "./store.js";
+import { useEffect } from "react";
+
+//#region src/deckgl/extensions/coffin-corner/use-coffin-corner.ts
+/**
+* Hook to manage coffin corner entity selection state.
+*
+* Automatically subscribes to map bus events for the given map and layer,
+* so you don't need onClick/onHover callbacks on the layer.
+*
+* @param mapId - The BaseMap instance ID
+* @param layerId - The deck.gl layer ID to listen for interactions on
+* @param options - Optional configuration for entity ID extraction
+*
+* @example
+* ```tsx
+* import { useCoffinCorner } from '@accelint/map-toolkit/deckgl/extensions/coffin-corner';
+*
+* function MapWithIcons({ mapId }) {
+*   const { selectedId, hoveredId } = useCoffinCorner(mapId, 'base-icons');
+*
+*   return (
+*     <iconLayer
+*       id="base-icons"
+*       pickable
+*       extensions={[coffinCornerExtension]}
+*       selectedEntityId={selectedId}
+*       hoveredEntityId={hoveredId}
+*     />
+*   );
+* }
+* ```
+*
+* @example Custom entity ID accessor
+* ```tsx
+* const { selectedId, hoveredId } = useCoffinCorner(mapId, 'geojson-icons', {
+*   getEntityId: (d) => d.properties?.shapeId,
+* });
+* ```
+*/
+function useCoffinCorner(mapId, layerId, options) {
+	const { state, setSelectedId, deselect, setLayerId, setGetEntityId } = coffinCornerStore.use(mapId);
+	useEffect(() => {
+		setLayerId(layerId);
+	}, [setLayerId, layerId]);
+	const getEntityId = options?.getEntityId;
+	useEffect(() => {
+		if (getEntityId) setGetEntityId(getEntityId);
+	}, [setGetEntityId, getEntityId]);
+	return {
+		selectedId: state.selectedId,
+		hoveredId: state.hoveredId,
+		setSelectedId,
+		deselect
+	};
+}
+
+//#endregion
+export { useCoffinCorner };
+//# sourceMappingURL=use-coffin-corner.js.map

package/dist/deckgl/extensions/coffin-corner/use-coffin-corner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-coffin-corner.js","names":[],"sources":["../../../../src/deckgl/extensions/coffin-corner/use-coffin-corner.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'use client';\n\nimport { useEffect } from 'react';\nimport { coffinCornerStore } from './store';\nimport type { UniqueId } from '@accelint/core';\nimport type { EntityId } from './types';\n\n/**\n * Return type for useCoffinCorner hook\n */\nexport type UseCoffinCornerReturn = {\n  /** Currently selected entity ID, or undefined if nothing selected */\n  selectedId: EntityId | undefined;\n  /** Currently hovered entity ID, or undefined if nothing hovered */\n  hoveredId: EntityId | undefined;\n  /** Set the selected entity ID */\n  setSelectedId: (id: EntityId | undefined) => void;\n  /** Clear the current selection */\n  deselect: () => void;\n};\n\n/**\n * Options for the useCoffinCorner hook.\n */\nexport type UseCoffinCornerOptions = {\n  /**\n   * Accessor to extract an entity ID from a picked data item.\n   * Must match the `getEntityId` prop passed to the CoffinCornerExtension.\n   * Should be a stable reference (module-level or `useCallback`) to avoid unnecessary store updates on every render.\n   * @default (item) => item.id\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: Data type is unknown at hook level.\n  getEntityId?: (item: any) => EntityId;\n};\n\n/**\n * Hook to manage coffin corner entity selection state.\n *\n * Automatically subscribes to map bus events for the given map and layer,\n * so you don't need onClick/onHover callbacks on the layer.\n *\n * @param mapId - The BaseMap instance ID\n * @param layerId - The deck.gl layer ID to listen for interactions on\n * @param options - Optional configuration for entity ID extraction\n *\n * @example\n * ```tsx\n * import { useCoffinCorner } from '@accelint/map-toolkit/deckgl/extensions/coffin-corner';\n *\n * function MapWithIcons({ mapId }) {\n *   const { selectedId, hoveredId } = useCoffinCorner(mapId, 'base-icons');\n *\n *   return (\n *     <iconLayer\n *       id=\"base-icons\"\n *       pickable\n *       extensions={[coffinCornerExtension]}\n *       selectedEntityId={selectedId}\n *       hoveredEntityId={hoveredId}\n *     />\n *   );\n * }\n * ```\n *\n * @example Custom entity ID accessor\n * ```tsx\n * const { selectedId, hoveredId } = useCoffinCorner(mapId, 'geojson-icons', {\n *   getEntityId: (d) => d.properties?.shapeId,\n * });\n * ```\n */\nexport function useCoffinCorner(\n  mapId: UniqueId,\n  layerId: string,\n  options?: UseCoffinCornerOptions,\n): UseCoffinCornerReturn {\n  const { state, setSelectedId, deselect, setLayerId, setGetEntityId } =\n    coffinCornerStore.use(mapId);\n\n  // Unlike a CompositeLayer, CoffinCornerExtension is a shader-only plugin\n  // with no picking handlers. The store must filter raw map bus events by\n  // layerId to know which clicks/hovers belong to this extension's layer.\n  useEffect(() => {\n    setLayerId(layerId);\n  }, [setLayerId, layerId]);\n\n  const getEntityId = options?.getEntityId;\n\n  useEffect(() => {\n    if (getEntityId) {\n      setGetEntityId(getEntityId);\n    }\n  }, [setGetEntityId, getEntityId]);\n\n  return {\n    selectedId: state.selectedId,\n    hoveredId: state.hoveredId,\n    setSelectedId,\n    deselect,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmFA,SAAgB,gBACd,OACA,SACA,SACuB;CACvB,MAAM,EAAE,OAAO,eAAe,UAAU,YAAY,mBAClD,kBAAkB,IAAI,MAAM;AAK9B,iBAAgB;AACd,aAAW,QAAQ;IAClB,CAAC,YAAY,QAAQ,CAAC;CAEzB,MAAM,cAAc,SAAS;AAE7B,iBAAgB;AACd,MAAI,YACF,gBAAe,YAAY;IAE5B,CAAC,gBAAgB,YAAY,CAAC;AAEjC,QAAO;EACL,YAAY,MAAM;EAClB,WAAW,MAAM;EACjB;EACA;EACD"}

package/dist/deckgl/extensions/index.d.ts

@@ -0,0 +1,15 @@
+/*
+ * Copyright 2026 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 { CoffinCornerExtensionProps } from "./coffin-corner/types.js";
+import { CoffinCornerExtension } from "./coffin-corner/coffin-corner-extension.js";
+export { CoffinCornerExtension, type CoffinCornerExtensionProps };

package/dist/deckgl/extensions/index.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2026 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 { CoffinCornerExtension } from "./coffin-corner/coffin-corner-extension.js";
+
+export { CoffinCornerExtension };

package/dist/deckgl/index.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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
@@ -14,12 +14,17 @@ import { MapEvents, MapEventsNamespace } from "./base-map/events.js";
 import { BaseMapProps, MapClickEvent, MapClickPayload, MapControlPayload, MapDisablePanEvent, MapDisableZoomEvent, MapEnablePanEvent, MapEnableZoomEvent, MapEventType, MapHoverEvent, MapHoverPayload } from "./base-map/types.js";
 import { DARK_BASE_MAP_STYLE, LIGHT_BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
 import { BaseMap } from "./base-map/index.js";
+import { CoffinCornerDeselectedEvent, CoffinCornerEvent, CoffinCornerEventType, CoffinCornerEvents, CoffinCornerExtensionProps, CoffinCornerHoveredEvent, CoffinCornerSelectedEvent, EntityId } from "./extensions/coffin-corner/types.js";
+import { CoffinCornerExtension } from "./extensions/coffin-corner/coffin-corner-extension.js";
+import { clearSelection, coffinCornerStore, getHoveredEntityId, getSelectedEntityId } from "./extensions/coffin-corner/store.js";
+import { UseCoffinCornerReturn, useCoffinCorner } from "./extensions/coffin-corner/use-coffin-corner.js";
+import "./extensions/coffin-corner/index.js";
 import { SavedViewportOptions, createSavedViewport } from "./saved-viewports/index.js";
-import { CircleProperties, CircleRadius, EllipseProperties, Shape, ShapeFeature, ShapeFeatureProperties, ShapeFeatureType, ShapeFeatureTypeValues, ShapeId, StyleProperties } from "./shapes/shared/types.js";
-import { DisplayShapeLayerProps, StyledFeature, StyledFeatureProperties } from "./shapes/display-shape-layer/types.js";
+import { CircleProperties, CircleRadius, EllipseProperties, Shape, ShapeFeature, ShapeFeatureProperties, ShapeFeatureType, ShapeId, StyleProperties, StyledFeature, StyledFeatureProperties } from "./shapes/shared/types.js";
+import { DisplayShapeLayerProps } from "./shapes/display-shape-layer/types.js";
 import { DisplayShapeLayer } from "./shapes/display-shape-layer/index.js";
 import { DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, LINE_PATTERNS, LINE_WIDTHS, SHAPE_LAYER_IDS } from "./shapes/shared/constants.js";
 import { ShapeEventType, ShapeEvents } from "./shapes/shared/events.js";
 import "./shapes/index.js";
 import { SymbolLayer, SymbolLayerProps } from "./symbol-layer/index.js";
-export { BaseMap, type BaseMapProps, type CircleProperties, type CircleRadius, DARK_BASE_MAP_STYLE, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, DisplayShapeLayer, type DisplayShapeLayerProps, type EllipseProperties, LIGHT_BASE_MAP_STYLE, LINE_PATTERNS, LINE_WIDTHS, type MapClickEvent, type MapClickPayload, type MapControlPayload, type MapDisablePanEvent, type MapDisableZoomEvent, type MapEnablePanEvent, type MapEnableZoomEvent, type MapEventType, MapEvents, MapEventsNamespace, type MapHoverEvent, type MapHoverPayload, PARAMETERS, SHAPE_LAYER_IDS, type SavedViewportOptions, type Shape, type ShapeEventType, ShapeEvents, type ShapeFeature, type ShapeFeatureProperties, ShapeFeatureType, type ShapeFeatureTypeValues, type ShapeId, type StyleProperties, type StyledFeature, type StyledFeatureProperties, SymbolLayer, type SymbolLayerProps, createSavedViewport };
+export { BaseMap, type BaseMapProps, type CircleProperties, type CircleRadius, type CoffinCornerDeselectedEvent, type CoffinCornerEvent, type CoffinCornerEventType, CoffinCornerEvents, CoffinCornerExtension, type CoffinCornerExtensionProps, type CoffinCornerHoveredEvent, type CoffinCornerSelectedEvent, DARK_BASE_MAP_STYLE, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, DisplayShapeLayer, type DisplayShapeLayerProps, type EllipseProperties, type EntityId, LIGHT_BASE_MAP_STYLE, LINE_PATTERNS, LINE_WIDTHS, type MapClickEvent, type MapClickPayload, type MapControlPayload, type MapDisablePanEvent, type MapDisableZoomEvent, type MapEnablePanEvent, type MapEnableZoomEvent, type MapEventType, MapEvents, MapEventsNamespace, type MapHoverEvent, type MapHoverPayload, PARAMETERS, SHAPE_LAYER_IDS, type SavedViewportOptions, type Shape, type ShapeEventType, ShapeEvents, type ShapeFeature, type ShapeFeatureProperties, ShapeFeatureType, type ShapeId, type StyleProperties, type StyledFeature, type StyledFeatureProperties, SymbolLayer, type SymbolLayerProps, type UseCoffinCornerReturn, clearSelection, coffinCornerStore, createSavedViewport, getHoveredEntityId, getSelectedEntityId, useCoffinCorner };

package/dist/deckgl/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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
@@ -17,8 +17,12 @@ import { ShapeFeatureType } from "./shapes/shared/types.js";
 import { DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, LINE_PATTERNS, LINE_WIDTHS, SHAPE_LAYER_IDS } from "./shapes/shared/constants.js";
 import { DARK_BASE_MAP_STYLE, LIGHT_BASE_MAP_STYLE, PARAMETERS } from "./base-map/constants.js";
 import { BaseMap } from "./base-map/index.js";
+import { CoffinCornerExtension } from "./extensions/coffin-corner/coffin-corner-extension.js";
+import { CoffinCornerEvents } from "./extensions/coffin-corner/types.js";
+import { clearSelection, coffinCornerStore, getHoveredEntityId, getSelectedEntityId } from "./extensions/coffin-corner/store.js";
+import { useCoffinCorner } from "./extensions/coffin-corner/use-coffin-corner.js";
 import { createSavedViewport } from "./saved-viewports/index.js";
 import { DisplayShapeLayer } from "./shapes/display-shape-layer/index.js";
 import { SymbolLayer } from "./symbol-layer/index.js";
 
-export { BaseMap, DARK_BASE_MAP_STYLE, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, DisplayShapeLayer, LIGHT_BASE_MAP_STYLE, LINE_PATTERNS, LINE_WIDTHS, MapEvents, MapEventsNamespace, PARAMETERS, SHAPE_LAYER_IDS, ShapeEvents, ShapeFeatureType, SymbolLayer, createSavedViewport };
+export { BaseMap, CoffinCornerEvents, CoffinCornerExtension, DARK_BASE_MAP_STYLE, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, DisplayShapeLayer, LIGHT_BASE_MAP_STYLE, LINE_PATTERNS, LINE_WIDTHS, MapEvents, MapEventsNamespace, PARAMETERS, SHAPE_LAYER_IDS, ShapeEvents, ShapeFeatureType, SymbolLayer, clearSelection, coffinCornerStore, createSavedViewport, getHoveredEntityId, getSelectedEntityId, useCoffinCorner };

package/dist/deckgl/saved-viewports/index.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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

package/dist/deckgl/saved-viewports/index.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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

package/dist/deckgl/saved-viewports/storage.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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

package/dist/deckgl/saved-viewports/storage.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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
@@ -11,15 +11,10 @@
  */
 
 
-import { getLogger } from "@accelint/logger";
+import { createLoggerDomain } from "../../shared/logger.js";
 
 //#region src/deckgl/saved-viewports/storage.ts
-const logger = getLogger({
-	enabled: process.env.NODE_ENV !== "production" && process.env.NODE_ENV !== "test",
-	level: "warn",
-	prefix: "[SavedViewports]",
-	pretty: true
-});
+const logger = createLoggerDomain("[SavedViewports]");
 /**
 * Base storage key for saved viewports in localStorage.
 */
@@ -41,8 +36,8 @@ const getContainerKey = (uniqueIdentifier) => uniqueIdentifier ? `${STORAGE_ID}-
 const getContainer = (containerKey) => {
 	try {
 		return JSON.parse(localStorage.getItem(containerKey) ?? "{}");
-	} catch {
-		logger.warn(`Failed to parse storage container for key: ${containerKey}, returning empty container.`);
+	} catch (err) {
+		logger.withError(err).error(`Failed to parse storage container for key: ${containerKey}, returning empty container.`);
 		return {};
 	}
 };

package/dist/deckgl/saved-viewports/storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"storage.js","names":[],"sources":["../../../src/deckgl/saved-viewports/storage.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\nimport { getLogger } from '@accelint/logger';\nimport type { MapViewState } from '@deck.gl/core';\n\nconst logger = getLogger({\n  enabled:\n    process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test',\n  level: 'warn',\n  prefix: '[SavedViewports]',\n  pretty: true,\n});\n\n/**\n * Base storage key for saved viewports in localStorage.\n */\nexport const STORAGE_ID = 'deckgl-saved-viewports';\n\n/**\n * Generates a storage key, optionally namespaced by unique identifier.\n *\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n * @returns Storage key string\n */\nconst getContainerKey = (uniqueIdentifier?: string) =>\n  uniqueIdentifier ? `${STORAGE_ID}-${uniqueIdentifier}` : STORAGE_ID;\n\n/**\n * Retrieves the storage container from localStorage.\n * Returns empty object if parsing fails or key doesn't exist.\n *\n * @param containerKey - The storage key to retrieve\n * @returns Parsed storage container object\n */\nconst getContainer = (containerKey: string) => {\n  try {\n    return JSON.parse(localStorage.getItem(containerKey) ?? '{}');\n  } catch {\n    logger.warn(\n      `Failed to parse storage container for key: ${containerKey}, returning empty container.`,\n    );\n    return {};\n  }\n};\n\n/**\n * Persists a viewport state to localStorage.\n *\n * Saves the viewport under the given ID within a namespaced container.\n * If the container doesn't exist, creates it. If the ID already exists, overwrites it.\n *\n * @param id - Unique identifier for this viewport (typically a key combination ID)\n * @param obj - The MapViewState to persist\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n *\n * @example\n * ```typescript\n * import { persist } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';\n *\n * const viewport = {\n *   latitude: 38.9072,\n *   longitude: -77.0369,\n *   zoom: 10,\n *   pitch: 0,\n *   bearing: 0,\n * };\n *\n * persist('Digit1', viewport);\n * persist('Digit2', viewport, 'main-map');\n * ```\n */\nexport const persist = (\n  id: string,\n  obj: MapViewState,\n  uniqueIdentifier?: string,\n) => {\n  const containerKey = getContainerKey(uniqueIdentifier);\n  const container = getContainer(containerKey);\n  container[id] = obj;\n  localStorage.setItem(containerKey, JSON.stringify(container));\n};\n\n/**\n * Retrieves a saved viewport state from localStorage.\n *\n * Returns the viewport associated with the given ID, or undefined if not found.\n * Logs a warning if the viewport doesn't exist.\n *\n * @param id - Unique identifier for the viewport to retrieve\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n * @returns The saved MapViewState or undefined if not found\n *\n * @example\n * ```typescript\n * import { retrieve } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';\n *\n * const viewport = retrieve('Digit1');\n * if (viewport) {\n *   console.log('Restored viewport:', viewport);\n * }\n *\n * const mainMapViewport = retrieve('Digit1', 'main-map');\n * ```\n */\nexport const retrieve = (id: string, uniqueIdentifier?: string) => {\n  const containerKey = getContainerKey(uniqueIdentifier);\n  const container = getContainer(containerKey);\n  const obj = container[id];\n  if (!obj) {\n    logger.warn(`Object with id: ${id} does not exist`);\n  }\n  return obj;\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,MAAM,SAAS,UAAU;CACvB,SACE,QAAQ,IAAI,aAAa,gBAAgB,QAAQ,IAAI,aAAa;CACpE,OAAO;CACP,QAAQ;CACR,QAAQ;CACT,CAAC;;;;AAKF,MAAa,aAAa;;;;;;;AAQ1B,MAAM,mBAAmB,qBACvB,mBAAmB,GAAG,WAAW,GAAG,qBAAqB;;;;;;;;AAS3D,MAAM,gBAAgB,iBAAyB;AAC7C,KAAI;AACF,SAAO,KAAK,MAAM,aAAa,QAAQ,aAAa,IAAI,KAAK;SACvD;AACN,SAAO,KACL,8CAA8C,aAAa,8BAC5D;AACD,SAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8Bb,MAAa,WACX,IACA,KACA,qBACG;CACH,MAAM,eAAe,gBAAgB,iBAAiB;CACtD,MAAM,YAAY,aAAa,aAAa;AAC5C,WAAU,MAAM;AAChB,cAAa,QAAQ,cAAc,KAAK,UAAU,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyB/D,MAAa,YAAY,IAAY,qBAA8B;CAGjE,MAAM,MADY,aADG,gBAAgB,iBAAiB,CACV,CACtB;AACtB,KAAI,CAAC,IACH,QAAO,KAAK,mBAAmB,GAAG,iBAAiB;AAErD,QAAO"}
+{"version":3,"file":"storage.js","names":[],"sources":["../../../src/deckgl/saved-viewports/storage.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\nimport { createLoggerDomain } from '@/shared/logger';\nimport type { MapViewState } from '@deck.gl/core';\n\nconst logger = createLoggerDomain('[SavedViewports]');\n\n/**\n * Base storage key for saved viewports in localStorage.\n */\nexport const STORAGE_ID = 'deckgl-saved-viewports';\n\n/**\n * Generates a storage key, optionally namespaced by unique identifier.\n *\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n * @returns Storage key string\n */\nconst getContainerKey = (uniqueIdentifier?: string) =>\n  uniqueIdentifier ? `${STORAGE_ID}-${uniqueIdentifier}` : STORAGE_ID;\n\n/**\n * Retrieves the storage container from localStorage.\n * Returns empty object if parsing fails or key doesn't exist.\n *\n * @param containerKey - The storage key to retrieve\n * @returns Parsed storage container object\n */\nconst getContainer = (containerKey: string) => {\n  try {\n    return JSON.parse(localStorage.getItem(containerKey) ?? '{}');\n  } catch (err) {\n    logger\n      .withError(err)\n      .error(\n        `Failed to parse storage container for key: ${containerKey}, returning empty container.`,\n      );\n\n    return {};\n  }\n};\n\n/**\n * Persists a viewport state to localStorage.\n *\n * Saves the viewport under the given ID within a namespaced container.\n * If the container doesn't exist, creates it. If the ID already exists, overwrites it.\n *\n * @param id - Unique identifier for this viewport (typically a key combination ID)\n * @param obj - The MapViewState to persist\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n *\n * @example\n * ```typescript\n * import { persist } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';\n *\n * const viewport = {\n *   latitude: 38.9072,\n *   longitude: -77.0369,\n *   zoom: 10,\n *   pitch: 0,\n *   bearing: 0,\n * };\n *\n * persist('Digit1', viewport);\n * persist('Digit2', viewport, 'main-map');\n * ```\n */\nexport const persist = (\n  id: string,\n  obj: MapViewState,\n  uniqueIdentifier?: string,\n) => {\n  const containerKey = getContainerKey(uniqueIdentifier);\n  const container = getContainer(containerKey);\n  container[id] = obj;\n  localStorage.setItem(containerKey, JSON.stringify(container));\n};\n\n/**\n * Retrieves a saved viewport state from localStorage.\n *\n * Returns the viewport associated with the given ID, or undefined if not found.\n * Logs a warning if the viewport doesn't exist.\n *\n * @param id - Unique identifier for the viewport to retrieve\n * @param uniqueIdentifier - Optional namespace for multiple map instances\n * @returns The saved MapViewState or undefined if not found\n *\n * @example\n * ```typescript\n * import { retrieve } from '@accelint/map-toolkit/deckgl/saved-viewports/storage';\n *\n * const viewport = retrieve('Digit1');\n * if (viewport) {\n *   console.log('Restored viewport:', viewport);\n * }\n *\n * const mainMapViewport = retrieve('Digit1', 'main-map');\n * ```\n */\nexport const retrieve = (id: string, uniqueIdentifier?: string) => {\n  const containerKey = getContainerKey(uniqueIdentifier);\n  const container = getContainer(containerKey);\n  const obj = container[id];\n  if (!obj) {\n    logger.warn(`Object with id: ${id} does not exist`);\n  }\n  return obj;\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,MAAM,SAAS,mBAAmB,mBAAmB;;;;AAKrD,MAAa,aAAa;;;;;;;AAQ1B,MAAM,mBAAmB,qBACvB,mBAAmB,GAAG,WAAW,GAAG,qBAAqB;;;;;;;;AAS3D,MAAM,gBAAgB,iBAAyB;AAC7C,KAAI;AACF,SAAO,KAAK,MAAM,aAAa,QAAQ,aAAa,IAAI,KAAK;UACtD,KAAK;AACZ,SACG,UAAU,IAAI,CACd,MACC,8CAA8C,aAAa,8BAC5D;AAEH,SAAO,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8Bb,MAAa,WACX,IACA,KACA,qBACG;CACH,MAAM,eAAe,gBAAgB,iBAAiB;CACtD,MAAM,YAAY,aAAa,aAAa;AAC5C,WAAU,MAAM;AAChB,cAAa,QAAQ,cAAc,KAAK,UAAU,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AAyB/D,MAAa,YAAY,IAAY,qBAA8B;CAGjE,MAAM,MADY,aADG,gBAAgB,iBAAiB,CACV,CACtB;AACtB,KAAI,CAAC,IACH,QAAO,KAAK,mBAAmB,GAAG,iBAAiB;AAErD,QAAO"}

package/dist/deckgl/shapes/display-shape-layer/constants.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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
@@ -14,6 +14,8 @@
 'use client';
 
 import { DEFAULT_COLORS } from "../shared/constants.js";
+import { CoffinCornerExtension } from "../../extensions/coffin-corner/coffin-corner-extension.js";
+import { PathStyleExtension } from "@deck.gl/extensions";
 
 //#region src/deckgl/shapes/display-shape-layer/constants.ts
 /**
@@ -28,29 +30,6 @@ const MAP_INTERACTION = {
 	ICON_HOVER_SIZE_INCREASE: 5
 };
 /**
-* Selection highlight configuration.
-*
-* Controls the appearance of selected shapes, including highlight color
-* and icon size adjustments for Point shapes.
-*/
-const SELECTION_HIGHLIGHT = {
-	COLOR: DEFAULT_COLORS.highlight,
-	ICON_SIZE_INCREASE: 8
-};
-/**
-* Coffin corners configuration for Point selection/hover feedback.
-*
-* Coffin corners are bracket-like corners that appear around Point shapes
-* with icons to indicate hover and selection states. They provide visual
-* feedback without obscuring the icon itself.
-*/
-const COFFIN_CORNERS = {
-	HOVER_ICON: "coffin-corners-hover",
-	SELECTED_ICON: "coffin-corners-selected",
-	SELECTED_HOVER_ICON: "coffin-corners-selected-hover",
-	SIZE: 38
-};
-/**
 * Default props for DisplayShapeLayer.
 *
 * Provides sensible defaults for interactive shape display with labels,
@@ -62,9 +41,74 @@ const DEFAULT_DISPLAY_PROPS = {
 	showLabels: "always",
 	showHighlight: false,
 	applyBaseOpacity: true,
-	highlightColor: SELECTION_HIGHLIGHT.COLOR
+	highlightColor: DEFAULT_COLORS.highlight
 };
+/**
+* Material settings for lighting effects on polygon shapes.
+* Controls fill brightness for hover and selection overlay layers.
+* Keys mirror BRIGHTNESS_FACTOR for consistency.
+*/
+const MATERIAL_SETTINGS = {
+	NORMAL: {
+		ambient: .35,
+		diffuse: .6,
+		shininess: 32,
+		specularColor: [
+			255,
+			255,
+			255
+		]
+	},
+	HOVER_OR_SELECT: {
+		ambient: .6,
+		diffuse: .8,
+		shininess: 64,
+		specularColor: [
+			255,
+			255,
+			255
+		]
+	},
+	HOVER_AND_SELECT: {
+		ambient: .75,
+		diffuse: .95,
+		shininess: 80,
+		specularColor: [
+			255,
+			255,
+			255
+		]
+	}
+};
+/**
+* Brightness multipliers for interaction state feedback.
+* Applied via brightenColor() to line colors, curtains, and elevation indicators.
+* - HOVER_OR_SELECT: shape is hovered or selected (single active state)
+* - HOVER_AND_SELECT: shape is both hovered and selected simultaneously
+*/
+const BRIGHTNESS_FACTOR = {
+	HOVER_OR_SELECT: 1.4,
+	HOVER_AND_SELECT: 1.7
+};
+/**
+* Opacity multiplier for interaction overlay layers (hover, select).
+* Applied to the shape's fill alpha — sits between the base opacity (0.2)
+* and full opacity (1.0) so the overlay reads clearly without being too solid.
+*/
+const OVERLAY_FILL_OPACITY = .25;
+/** Reusable deck.gl PathStyleExtension enabling dash patterns on GeoJsonLayer lines. */
+const DASH_EXTENSION = new PathStyleExtension({ dash: true });
+const COFFIN_CORNER_EXTENSION = new CoffinCornerExtension();
+/** Stable extensions array for GeoJsonLayer — avoids new reference per render triggering getShaders() re-evaluation. */
+const DISPLAY_EXTENSIONS = [DASH_EXTENSION, COFFIN_CORNER_EXTENSION];
+/** Readonly [r, g, b, a] tuple of DEFAULT_COLORS.highlight, pre-spread at module load for hot-path usage. */
+const HIGHLIGHT_COLOR_TUPLE = [
+	DEFAULT_COLORS.highlight[0],
+	DEFAULT_COLORS.highlight[1],
+	DEFAULT_COLORS.highlight[2],
+	DEFAULT_COLORS.highlight[3] ?? 255
+];
 
 //#endregion
-export { COFFIN_CORNERS, DEFAULT_DISPLAY_PROPS, MAP_INTERACTION };
+export { BRIGHTNESS_FACTOR, DEFAULT_DISPLAY_PROPS, DISPLAY_EXTENSIONS, HIGHLIGHT_COLOR_TUPLE, MAP_INTERACTION, MATERIAL_SETTINGS, OVERLAY_FILL_OPACITY };
 //# sourceMappingURL=constants.js.map

package/dist/deckgl/shapes/display-shape-layer/constants.js.map

@@ -1 +1 @@
-{"version":3,"file":"constants.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/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\n'use client';\n\nimport { DEFAULT_COLORS } from '../shared/constants';\n\n/**\n * Map interaction constants.\n *\n * Values derived from ngc2 for consistency with existing UI patterns.\n * Controls sizing and interaction feedback for shape rendering.\n */\nexport const MAP_INTERACTION = {\n  LINE_WIDTH_MIN_PIXELS: 1, // Minimum line width in pixels\n  ICON_SIZE: 38, // Size of shape icons\n  ICON_HOVER_SIZE_INCREASE: 5, // Additional pixels added on hover\n} as const;\n\n/**\n * Selection highlight configuration.\n *\n * Controls the appearance of selected shapes, including highlight color\n * and icon size adjustments for Point shapes.\n */\nexport const SELECTION_HIGHLIGHT = {\n  /** Uses DEFAULT_COLORS.highlight from shared constants */\n  COLOR: DEFAULT_COLORS.highlight,\n  ICON_SIZE_INCREASE: 8, // Additional pixels for highlight icon\n} as const;\n\n/**\n * Coffin corners configuration for Point selection/hover feedback.\n *\n * Coffin corners are bracket-like corners that appear around Point shapes\n * with icons to indicate hover and selection states. They provide visual\n * feedback without obscuring the icon itself.\n */\nexport const COFFIN_CORNERS = {\n  /** Icon name for hover state (white corners with background fill) */\n  HOVER_ICON: 'coffin-corners-hover',\n  /** Icon name for selected state (blue corners, no fill) */\n  SELECTED_ICON: 'coffin-corners-selected',\n  /** Icon name for selected+hover state (blue corners with background fill) */\n  SELECTED_HOVER_ICON: 'coffin-corners-selected-hover',\n  /** Size of the coffin corners icon */\n  SIZE: 38,\n} as const;\n\n/**\n * Default props for DisplayShapeLayer.\n *\n * Provides sensible defaults for interactive shape display with labels,\n * standard opacity handling, and minimal visual feedback. These can be\n * overridden via layer props.\n */\nexport const DEFAULT_DISPLAY_PROPS = {\n  pickable: true,\n  showLabels: 'always' as const,\n  showHighlight: false,\n  applyBaseOpacity: true,\n  highlightColor: SELECTION_HIGHLIGHT.COLOR,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,kBAAkB;CAC7B,uBAAuB;CACvB,WAAW;CACX,0BAA0B;CAC3B;;;;;;;AAQD,MAAa,sBAAsB;CAEjC,OAAO,eAAe;CACtB,oBAAoB;CACrB;;;;;;;;AASD,MAAa,iBAAiB;CAE5B,YAAY;CAEZ,eAAe;CAEf,qBAAqB;CAErB,MAAM;CACP;;;;;;;;AASD,MAAa,wBAAwB;CACnC,UAAU;CACV,YAAY;CACZ,eAAe;CACf,kBAAkB;CAClB,gBAAgB,oBAAoB;CACrC"}
+{"version":3,"file":"constants.js","names":["HIGHLIGHT_COLOR_TUPLE: Rgba255Tuple"],"sources":["../../../../src/deckgl/shapes/display-shape-layer/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\n'use client';\nimport { PathStyleExtension } from '@deck.gl/extensions';\nimport { CoffinCornerExtension } from '../../extensions/coffin-corner/coffin-corner-extension';\nimport { DEFAULT_COLORS } from '../shared/constants';\nimport type { Rgba255Tuple } from '@accelint/predicates';\n\n/**\n * Map interaction constants.\n *\n * Values derived from ngc2 for consistency with existing UI patterns.\n * Controls sizing and interaction feedback for shape rendering.\n */\nexport const MAP_INTERACTION = {\n  LINE_WIDTH_MIN_PIXELS: 1,\n  ICON_SIZE: 38,\n  ICON_HOVER_SIZE_INCREASE: 5,\n} as const;\n\n/**\n * Default props for DisplayShapeLayer.\n *\n * Provides sensible defaults for interactive shape display with labels,\n * standard opacity handling, and minimal visual feedback. These can be\n * overridden via layer props.\n */\nexport const DEFAULT_DISPLAY_PROPS = {\n  pickable: true,\n  showLabels: 'always' as const,\n  showHighlight: false,\n  applyBaseOpacity: true,\n  highlightColor: DEFAULT_COLORS.highlight,\n};\n\n/**\n * Material settings for lighting effects on polygon shapes.\n * Controls fill brightness for hover and selection overlay layers.\n * Keys mirror BRIGHTNESS_FACTOR for consistency.\n */\nexport const MATERIAL_SETTINGS = {\n  // Normal state - standard lighting\n  NORMAL: {\n    ambient: 0.35,\n    diffuse: 0.6,\n    shininess: 32,\n    specularColor: [255, 255, 255] as [number, number, number],\n  },\n  // Hovered or selected (single active state)\n  HOVER_OR_SELECT: {\n    ambient: 0.6,\n    diffuse: 0.8,\n    shininess: 64,\n    specularColor: [255, 255, 255] as [number, number, number],\n  },\n  // Hovered and selected simultaneously - brighter\n  HOVER_AND_SELECT: {\n    ambient: 0.75,\n    diffuse: 0.95,\n    shininess: 80,\n    specularColor: [255, 255, 255] as [number, number, number],\n  },\n} as const;\n\n/**\n * Brightness multipliers for interaction state feedback.\n * Applied via brightenColor() to line colors, curtains, and elevation indicators.\n * - HOVER_OR_SELECT: shape is hovered or selected (single active state)\n * - HOVER_AND_SELECT: shape is both hovered and selected simultaneously\n */\nexport const BRIGHTNESS_FACTOR = {\n  HOVER_OR_SELECT: 1.4,\n  HOVER_AND_SELECT: 1.7,\n} as const;\n\n/**\n * Opacity multiplier for interaction overlay layers (hover, select).\n * Applied to the shape's fill alpha — sits between the base opacity (0.2)\n * and full opacity (1.0) so the overlay reads clearly without being too solid.\n */\nexport const OVERLAY_FILL_OPACITY = 0.25;\n\n/** Reusable deck.gl PathStyleExtension enabling dash patterns on GeoJsonLayer lines. */\nexport const DASH_EXTENSION = new PathStyleExtension({ dash: true });\n\nexport const COFFIN_CORNER_EXTENSION = new CoffinCornerExtension();\n\n/** Stable extensions array for GeoJsonLayer — avoids new reference per render triggering getShaders() re-evaluation. */\nexport const DISPLAY_EXTENSIONS = [DASH_EXTENSION, COFFIN_CORNER_EXTENSION];\n\n/** Readonly [r, g, b, a] tuple of DEFAULT_COLORS.highlight, pre-spread at module load for hot-path usage. */\nexport const HIGHLIGHT_COLOR_TUPLE: Rgba255Tuple = [\n  DEFAULT_COLORS.highlight[0],\n  DEFAULT_COLORS.highlight[1],\n  DEFAULT_COLORS.highlight[2],\n  DEFAULT_COLORS.highlight[3] ?? 255,\n];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAwBA,MAAa,kBAAkB;CAC7B,uBAAuB;CACvB,WAAW;CACX,0BAA0B;CAC3B;;;;;;;;AASD,MAAa,wBAAwB;CACnC,UAAU;CACV,YAAY;CACZ,eAAe;CACf,kBAAkB;CAClB,gBAAgB,eAAe;CAChC;;;;;;AAOD,MAAa,oBAAoB;CAE/B,QAAQ;EACN,SAAS;EACT,SAAS;EACT,WAAW;EACX,eAAe;GAAC;GAAK;GAAK;GAAI;EAC/B;CAED,iBAAiB;EACf,SAAS;EACT,SAAS;EACT,WAAW;EACX,eAAe;GAAC;GAAK;GAAK;GAAI;EAC/B;CAED,kBAAkB;EAChB,SAAS;EACT,SAAS;EACT,WAAW;EACX,eAAe;GAAC;GAAK;GAAK;GAAI;EAC/B;CACF;;;;;;;AAQD,MAAa,oBAAoB;CAC/B,iBAAiB;CACjB,kBAAkB;CACnB;;;;;;AAOD,MAAa,uBAAuB;;AAGpC,MAAa,iBAAiB,IAAI,mBAAmB,EAAE,MAAM,MAAM,CAAC;AAEpE,MAAa,0BAA0B,IAAI,uBAAuB;;AAGlE,MAAa,qBAAqB,CAAC,gBAAgB,wBAAwB;;AAG3E,MAAaA,wBAAsC;CACjD,eAAe,UAAU;CACzB,eAAe,UAAU;CACzB,eAAe,UAAU;CACzB,eAAe,UAAU,MAAM;CAChC"}

package/dist/deckgl/shapes/display-shape-layer/fiber.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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

package/dist/deckgl/shapes/display-shape-layer/fiber.js

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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

package/dist/deckgl/shapes/display-shape-layer/index.d.ts

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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
@@ -10,23 +10,12 @@
  * governing permissions and limitations under the License.
  */
 
-import { ShapeId } from "../shared/types.js";
-import { DisplayShapeLayerProps } from "./types.js";
+import { DisplayShapeLayerProps, DisplayShapeLayerState } from "./types.js";
 import * as _deck_gl_core0 from "@deck.gl/core";
 import { CompositeLayer, Layer, PickingInfo } from "@deck.gl/core";
 
 //#region src/deckgl/shapes/display-shape-layer/index.d.ts
-/**
- * State type for DisplayShapeLayer
- */
-type DisplayShapeLayerState = {
-  /** Index of currently hovered shape, undefined when not hovering */
-  hoverIndex?: number;
-  /** ID of the last hovered shape for event deduplication */
-  lastHoveredId?: ShapeId | null;
-  /** Allow additional properties from base layer state */
-  [key: string]: unknown;
-};
+
 /**
  * DisplayShapeLayer - Read-only shapes visualization layer
  *
@@ -36,24 +25,28 @@ type DisplayShapeLayerState = {
  * ## Features
  * - **Multiple geometry types**: Point, LineString, Polygon, and Circle
  * - **Icon support**: Custom icons for Point geometries via icon atlases
- * - **Interactive selection**: Click handling with dotted border and optional highlight
- * - **Hover effects**: Border/outline width increases on hover for better UX
+ * - **Interactive selection**: Click handling with brightness overlay on polygon select, optional highlight outline for non-Point shapes (if showHighlight=true). Point geometries use coffin corner brackets instead.
+ * - **Hover effects**: Polygon fills brighten via material lighting; outline width increases by 2px on hover
  * - **Customizable labels**: Flexible label positioning with per-shape or global options
  * - **Style properties**: Full control over colors, border/outline patterns, and opacity
  * - **Event bus integration**: Automatically emits shape events via @accelint/bus
  * - **Multi-map support**: Events include map instance ID for isolation
  *
- * ## Selection Visual Feedback
- * When a shape is selected via `selectedShapeId`:
- * - The shape's border/outline pattern changes to dotted
- * - An optional highlight renders underneath (controlled by `showHighlight` prop)
+ * ## Interaction Philosophy
+ * Interactions never modify a shape's innate styling. Hover and selection are always
+ * additive overlays rendered apart from the main layer using opacity-scaled fill colors
+ * and material-based brightness — the base shape is never altered.
  *
  * ## Layer Structure
- * Renders up to four sublayers (in order, bottom to top):
- * 1. **Highlight layer**: Selection highlight effect for non-icon-Point shapes (if showHighlight=true)
- * 2. **Coffin corners layer**: Selection/hover feedback for Point shapes with icons
- * 3. **Main GeoJsonLayer**: Shape geometries with styling and interaction
- * 4. **Label layer**: Text labels (if showLabels enabled)
+ * Renders sublayers in this order (bottom to top):
+ * 1. **Highlight layer**: Selection outline for non-polygon, non-Point shapes (when showHighlight enabled)
+ * 2. **Select layer**: Selection brightness overlay for polygon shapes
+ * 3. **Hover layer**: Hover brightness overlay for polygon shapes
+ * 4. **Elevation visualization**: Curtains (LineStrings) or wireframes (polygons) — elevation only
+ * 5. **Elevation indicators**: Vertical strut lines for elevated non-polygon shapes — elevation only
+ * 6. **Main GeoJsonLayer**: Shape geometries with styling and interaction; includes CoffinCornerExtension
+ *    which propagates to the icon/scatterplot sublayer for Point hover/select bracket feedback
+ * 7. **Label layer**: Text labels (if showLabels enabled)
  *
  * ## Icon Atlas Constraint
  * When using icons for Point geometries, all shapes in a single layer must share the
@@ -115,6 +108,12 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
   state: DisplayShapeLayerState;
   /** Cache for transformed features to avoid recreating objects on every render */
   private featuresCache;
+  /** Cache for elevation classification and curtain features */
+  private elevationCache;
+  /** Cache for elevation indicator line segments */
+  private indicatorCache;
+  /** Cached coffin corner color tuple — avoids new array reference per render when highlight hasn't changed. */
+  private coffinCornerColorCache;
   static layerName: string;
   static defaultProps: {
     pickable: boolean;
@@ -127,6 +126,23 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
    * Clean up state and caches when layer is destroyed
    */
   finalizeState(): void;
+  /**
+   * Resolved highlight color — uses prop if provided, falls back to default.
+   */
+  private get resolvedHighlight();
+  /**
+   * Coffin corner bracket color derived from resolvedHighlight with forced full opacity.
+   * Cached to avoid a new array reference per render triggering deck.gl prop-change detection.
+   */
+  private get coffinCornerColor();
+  /**
+   * Handle picking events from the main shapes layer
+   */
+  private handleMainLayerPick;
+  /**
+   * Handle picking events from curtain layers and map back to original LineString
+   */
+  private handleCurtainPick;
   /**
    * Override getPickingInfo to handle events from sublayers
    * This is the correct pattern for CompositeLayer event handling
@@ -138,7 +154,7 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
   }: {
     info: PickingInfo;
     mode?: string;
-    sourceLayer?: any;
+    sourceLayer?: Layer | null;
   }): {
     color: Uint8Array | null;
     layer: Layer | null;
@@ -165,29 +181,38 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
    */
   private getShapeById;
   /**
-   * Handle shape click
+   * Handle shape click — emits `shapes:selected` via bus and calls `onShapeClick` callback.
+   * @param info - deck.gl picking info from the clicked sublayer.
    */
   private handleShapeClick;
   /**
-   * Handle shape hover
+   * Handle shape hover — emits `shapes:hovered` via bus (deduplicated by shapeId) and calls `onShapeHover` callback.
+   * @param info - deck.gl picking info from the hovered sublayer.
    */
   private handleShapeHover;
   /**
-   * Render highlight sublayer (underneath main layer)
-   * Note: Points with icons use coffin corners instead of highlight layer
+   * Get or compute elevation-derived data (feature classification + curtain features).
+   * Cached on features identity and applyBaseOpacity to avoid per-frame recomputation.
+   */
+  private getElevationData;
+  /**
+   * Render highlight sublayer (underneath main layer).
+   * Point geometries skip this layer — they use coffin corner brackets
+   * via CoffinCornerExtension on the main layer's icon/scatterplot sublayer instead.
    */
   private renderHighlightLayer;
   /**
-   * Render coffin corners layer for Point geometries that have icons on hover/select
-   * Coffin corners provide visual feedback for points instead of highlight layer
+   * Render selection overlay layer for polygon shapes.
+   * Mirrors renderHoverLayer but triggers on selectedShapeId instead of hover.
+   * When a shape is both selected and hovered, both layers stack for a brighter combined effect.
    */
-  private renderCoffinCornersLayer;
+  private renderSelectLayer;
   /**
-   * Extract icon configuration from features in a single pass.
-   * Returns the first icon's atlas and mapping (all shapes share the same atlas).
-   * Uses early return for O(1) best case when first feature has icons.
+   * Render hover layer for all polygon shapes (2D and 3D).
+   * Overlays the shape's base fill with brighter material lighting.
+   * Stacks with other interaction layers (e.g. selection highlight underneath).
    */
-  private getIconConfig;
+  private renderHoverLayer;
   /**
    * Render main shapes layer
    */
@@ -201,7 +226,37 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
    */
   private renderLabelsLayer;
   /**
-   * Render all sublayers
+   * Render radius label layer for hovered circle shapes.
+   * Shows the circle's radius value converted to the configured display unit.
+   *
+   * Positioning relative to the shape's label:
+   * - When showLabels is 'always' or 'hover': appears below the label
+   * - When showLabels is 'never': appears in the label's position
+   */
+  private renderRadiusLabelLayer;
+  /**
+   * Render vertical elevation indicator lines for non-polygon shapes.
+   * Creates vertical "strut" lines from ground level to elevated features.
+   * For LineStrings, creates a "curtain" effect with vertical lines at each coordinate.
+   * Polygons use wireframe extrusion instead.
+   */
+  private renderElevationIndicatorLayer;
+  /**
+   * Create a single curtain GeoJsonLayer with shared configuration.
+   */
+  private createCurtainGeoJsonLayer;
+  /**
+   * Render curtain layers for elevated LineStrings.
+   * Creates three separate layers for main, hovered, and selected states.
+   */
+  private renderCurtainLayers;
+  /**
+   * Render elevation visualization layers (curtains for lines, wireframes for polygons).
+   */
+  private renderElevationVisualizationLayer;
+  /**
+   * Render all sublayers.
+   * @returns Ordered array of sublayers (highlight, select, hover, elevation, main, labels) from bottom to top.
    */
   renderLayers(): Layer[];
 }