@accelint/map-toolkit 0.5.0 → 0.6.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/index.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\n'use client';\n\nimport { Broadcast } from '@accelint/bus';\nimport { CompositeLayer } from '@deck.gl/core';\nimport { PathStyleExtension } from '@deck.gl/extensions';\nimport { GeoJsonLayer, IconLayer } from '@deck.gl/layers';\nimport { DASH_ARRAYS, SHAPE_LAYER_IDS } from '../shared/constants';\nimport { type ShapeEvent, ShapeEvents } from '../shared/events';\nimport {\n  COFFIN_CORNERS,\n  DEFAULT_DISPLAY_PROPS,\n  MAP_INTERACTION,\n} from './constants';\nimport { createShapeLabelLayer } from './shape-label-layer';\nimport {\n  getDashArray,\n  getFillColor,\n  getHighlightColor,\n  getHighlightLineWidth,\n  getHoverLineWidth,\n  getStrokeColor,\n} from './utils/display-style';\nimport type { Layer, PickingInfo } from '@deck.gl/core';\nimport type { EditableShape, ShapeId } from '../shared/types';\nimport type { DisplayShapeLayerProps } from './types';\n\n/**\n * Typed event bus instance for shape events.\n * Provides type-safe event emission for shape interactions.\n */\nconst shapeBus = Broadcast.getInstance<ShapeEvent>();\n\n/**\n * State interface for DisplayShapeLayer\n */\ninterface DisplayShapeLayerState {\n  /** Index of currently hovered shape, undefined when not hovering */\n  hoverIndex?: number;\n  /** ID of the last hovered shape for event deduplication */\n  lastHoveredId?: ShapeId | null;\n  /** Allow additional properties from base layer state */\n  [key: string]: unknown;\n}\n\n/**\n * Cache for transformed features to avoid recreating objects on every render.\n */\ninterface FeaturesCache {\n  /** Reference to the original data array for identity comparison */\n  data: EditableShape[];\n  /** Transformed features with shapeId added to properties */\n  features: EditableShape['feature'][];\n}\n\n/**\n * DisplayShapeLayer - Read-only shapes visualization layer\n *\n * A composite deck.gl layer for displaying geographic shapes with interactive features.\n * Ideal for rendering shapes from external APIs or displaying read-only geographic data.\n *\n * ## Features\n * - **Multiple geometry types**: Point, LineString, Polygon, and Circle\n * - **Icon support**: Custom icons for Point geometries via icon atlases\n * - **Interactive selection**: Click handling with dotted border and optional highlight\n * - **Hover effects**: Line width increases on hover for better UX\n * - **Customizable labels**: Flexible label positioning with per-shape or global options\n * - **Style properties**: Full control over colors, stroke patterns, and opacity\n * - **Event bus integration**: Automatically emits shape events via @accelint/bus\n * - **Multi-map support**: Events include map instance ID for isolation\n *\n * ## Selection Visual Feedback\n * When a shape is selected via `selectedShapeId`:\n * - The shape's stroke pattern changes to dotted\n * - An optional highlight renders underneath (controlled by `showHighlight` prop)\n *\n * ## Layer Structure\n * Renders up to four sublayers (in order, bottom to top):\n * 1. **Highlight layer**: Selection highlight effect for non-icon-Point shapes (if showHighlight=true)\n * 2. **Coffin corners layer**: Selection/hover feedback for Point shapes with icons\n * 3. **Main GeoJsonLayer**: Shape geometries with styling and interaction\n * 4. **Label layer**: Text labels (if showLabels enabled)\n *\n * ## Icon Atlas Constraint\n * When using icons for Point geometries, all shapes in a single layer must share the\n * same icon atlas. The layer uses the first atlas found across all features. If you\n * need icons from different atlases, use separate DisplayShapeLayer instances.\n *\n * ## Event Bus Integration\n * Automatically emits shape events that can be consumed anywhere in your app:\n * - `shapes:selected` - Emitted when a shape is clicked (includes mapId)\n * - `shapes:hovered` - Emitted when the hovered shape changes (deduplicated, includes mapId)\n *\n * For selection with auto-deselection, use the companion `useShapeSelection` hook which handles\n * all the event wiring automatically. See the example below.\n *\n * @example Basic usage with useShapeSelection hook (recommended)\n * ```tsx\n * import '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/fiber';\n * import { useShapeSelection } from '@accelint/map-toolkit/deckgl/shapes';\n * import { uuid } from '@accelint/core';\n *\n * const MAP_ID = uuid();\n *\n * function MapWithShapes() {\n *   const { selectedId } = useShapeSelection(MAP_ID);\n *\n *   return (\n *     <BaseMap id={MAP_ID}>\n *       <displayShapeLayer\n *         id=\"my-shapes\"\n *         mapId={MAP_ID}\n *         data={shapes}\n *         selectedShapeId={selectedId}\n *         showLabels={true}\n *         pickable={true}\n *       />\n *     </BaseMap>\n *   );\n * }\n * ```\n *\n * @example With custom label positioning\n * ```tsx\n * <displayShapeLayer\n *   id=\"my-shapes\"\n *   data={shapes}\n *   showLabels={true}\n *   labelOptions={{\n *     // Position circle labels at the top\n *     circleLabelCoordinateAnchor: 'top',\n *     circleLabelVerticalAnchor: 'bottom',\n *     circleLabelOffset: [0, -10],\n *     // Position line labels at the middle\n *     lineStringLabelCoordinateAnchor: 'middle',\n *   }}\n * />\n * ```\n */\nexport class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {\n  // State is typed via DisplayShapeLayerState but deck.gl doesn't support generic state\n  declare state: DisplayShapeLayerState;\n\n  /** Cache for transformed features to avoid recreating objects on every render */\n  private featuresCache: FeaturesCache | null = null;\n\n  static override layerName = 'DisplayShapeLayer';\n\n  static override defaultProps = {\n    ...DEFAULT_DISPLAY_PROPS,\n  };\n\n  /**\n   * Clean up state and caches when layer is destroyed\n   */\n  override finalizeState(): void {\n    // Clear hover state to prevent stale references\n    if (this.state?.hoverIndex !== undefined) {\n      this.setState({ hoverIndex: undefined, lastHoveredId: undefined });\n    }\n    // Clear features cache\n    this.featuresCache = null;\n  }\n\n  /**\n   * Override getPickingInfo to handle events from sublayers\n   * This is the correct pattern for CompositeLayer event handling\n   */\n  override getPickingInfo({\n    info,\n    mode,\n    sourceLayer,\n  }: {\n    info: PickingInfo;\n    mode?: string;\n    // biome-ignore lint/suspicious/noExplicitAny: sourceLayer type from deck.gl is not well-typed\n    sourceLayer?: any;\n  }) {\n    // Check if this picking event came from our main shapes layer\n    if (sourceLayer?.id === `${this.props.id}-${SHAPE_LAYER_IDS.DISPLAY}`) {\n      // Handle click events (deck.gl uses 'query' mode for clicks)\n      if (mode === 'query') {\n        this.handleShapeClick(info);\n      }\n\n      // Handle hover events (including when mode is undefined, which is hover)\n      if (mode === 'hover' || !mode) {\n        // Update hover state\n        if (info.index !== undefined && info.index !== this.state?.hoverIndex) {\n          this.setState({ hoverIndex: info.index });\n        } else if (\n          info.index === undefined &&\n          this.state?.hoverIndex !== undefined\n        ) {\n          this.setState({ hoverIndex: undefined });\n        }\n\n        // Call hover callback\n        this.handleShapeHover(info);\n      }\n    }\n\n    return info;\n  }\n\n  /**\n   * Convert shapes to GeoJSON features with shapeId in properties.\n   * Uses caching to avoid recreating objects on every render cycle.\n   */\n  private getFeaturesWithId(): EditableShape['feature'][] {\n    const { data } = this.props;\n\n    // Return cached features if data hasn't changed (identity check)\n    if (this.featuresCache?.data === data) {\n      return this.featuresCache.features;\n    }\n\n    // Transform features and cache the result\n    const features = data.map((shape) => ({\n      ...shape.feature,\n      properties: {\n        ...shape.feature.properties,\n        shapeId: shape.id,\n      },\n    }));\n\n    this.featuresCache = { data, features };\n    return features;\n  }\n\n  /**\n   * Look up a shape by ID from the data prop.\n   * Used by event handlers to get full shape without storing in feature properties.\n   */\n  private getShapeById(shapeId: ShapeId): EditableShape | undefined {\n    return this.props.data.find((shape) => shape.id === shapeId);\n  }\n\n  /**\n   * Handle shape click\n   */\n  private handleShapeClick = (info: PickingInfo): void => {\n    const { onShapeClick, mapId } = this.props;\n\n    if (!info.object) {\n      return;\n    }\n\n    // Look up shape from data prop using shapeId stored in feature properties\n    const shapeId = info.object.properties?.shapeId as ShapeId | undefined;\n    if (!shapeId) {\n      return;\n    }\n\n    const shape = this.getShapeById(shapeId);\n    if (!shape) {\n      return;\n    }\n\n    // Emit shape selected event via bus (include mapId for multi-map isolation)\n    shapeBus.emit(ShapeEvents.selected, { shapeId: shape.id, mapId });\n\n    // Call callback if provided\n    if (onShapeClick) {\n      onShapeClick(shape);\n    }\n  };\n\n  /**\n   * Handle shape hover\n   */\n  private handleShapeHover = (info: PickingInfo): void => {\n    const { onShapeHover, mapId } = this.props;\n\n    // Look up shape from data prop using shapeId stored in feature properties\n    const shapeId =\n      (info.object?.properties?.shapeId as ShapeId | undefined) ?? null;\n    const shape = shapeId ? (this.getShapeById(shapeId) ?? null) : null;\n\n    // Dedupe hover events - only emit if hovered shape changed\n    if (shapeId !== this.state?.lastHoveredId) {\n      this.setState({ lastHoveredId: shapeId });\n\n      // Emit shape hovered event via bus (include mapId for multi-map isolation)\n      shapeBus.emit(ShapeEvents.hovered, {\n        shapeId,\n        mapId,\n      });\n    }\n\n    // Always call callback if provided (for local state updates)\n    if (onShapeHover) {\n      onShapeHover(shape);\n    }\n  };\n\n  /**\n   * Render highlight sublayer (underneath main layer)\n   * Note: Points with icons use coffin corners instead of highlight layer\n   */\n  private renderHighlightLayer(\n    features: EditableShape['feature'][],\n  ): GeoJsonLayer | null {\n    const { selectedShapeId, showHighlight, highlightColor } = this.props;\n\n    if (!selectedShapeId || showHighlight === false) {\n      return null;\n    }\n\n    const selectedFeature = features.find(\n      (f) => f.properties?.shapeId === selectedShapeId,\n    );\n\n    if (!selectedFeature) {\n      return null;\n    }\n\n    // Skip highlight layer for Point geometries with icons - they use coffin corners instead\n    // Points without icons should still show the highlight layer\n    if (selectedFeature.geometry.type === 'Point') {\n      const hasIcon = !!selectedFeature.properties?.styleProperties?.icon;\n      if (hasIcon) {\n        return null;\n      }\n    }\n\n    return new GeoJsonLayer({\n      id: `${this.props.id}-${SHAPE_LAYER_IDS.DISPLAY_HIGHLIGHT}`,\n      // biome-ignore lint/suspicious/noExplicitAny: GeoJsonLayer accepts various feature formats\n      data: [selectedFeature] as any,\n\n      // Styling\n      filled: true,\n      stroked: true,\n      lineWidthUnits: 'pixels',\n      lineWidthMinPixels: MAP_INTERACTION.LINE_WIDTH_MIN_PIXELS,\n      getFillColor: () => [0, 0, 0, 0], // Transparent fill\n      getLineColor: () => highlightColor || getHighlightColor(),\n      getLineWidth: getHighlightLineWidth,\n\n      // Behavior\n      pickable: false,\n      updateTriggers: {\n        getLineColor: [highlightColor],\n        getLineWidth: [selectedShapeId, features],\n      },\n    });\n  }\n\n  /**\n   * Render coffin corners layer for Point geometries that have icons on hover/select\n   * Coffin corners provide visual feedback for points instead of highlight layer\n   */\n  private renderCoffinCornersLayer(\n    features: EditableShape['feature'][],\n  ): IconLayer | null {\n    const { selectedShapeId } = this.props;\n\n    // Find point features that need coffin corners (hovered or selected)\n    const pointFeatures = features.filter((f) => {\n      if (f.geometry.type !== 'Point') {\n        return false;\n      }\n      const hasIcon = !!f.properties?.styleProperties?.icon;\n      if (!hasIcon) {\n        return false;\n      }\n\n      const shapeId = f.properties?.shapeId;\n      const isSelected = shapeId === selectedShapeId;\n      const isHovered =\n        this.state?.hoverIndex !== undefined &&\n        features.indexOf(f) === this.state.hoverIndex;\n\n      return isSelected || isHovered;\n    });\n\n    if (pointFeatures.length === 0) {\n      return null;\n    }\n\n    // Get icon atlas from first point feature (all should share the same atlas)\n    const firstPointIcon = pointFeatures[0]?.properties?.styleProperties?.icon;\n    const iconAtlas = firstPointIcon?.atlas;\n    const iconMapping = firstPointIcon?.mapping;\n\n    if (!iconAtlas) {\n      return null;\n    }\n\n    if (!iconMapping) {\n      return null;\n    }\n\n    // Add coffin corners icons to the mapping\n    const extendedMapping = {\n      ...iconMapping,\n      [COFFIN_CORNERS.HOVER_ICON]: {\n        x: 0,\n        y: 0,\n        width: 76,\n        height: 76,\n        mask: false,\n      },\n      [COFFIN_CORNERS.SELECTED_ICON]: {\n        x: 76,\n        y: 0,\n        width: 76,\n        height: 76,\n        mask: false,\n      },\n      [COFFIN_CORNERS.SELECTED_HOVER_ICON]: {\n        x: 152,\n        y: 0,\n        width: 76,\n        height: 76,\n        mask: false,\n      },\n    };\n\n    return new IconLayer({\n      id: `${this.props.id}-${SHAPE_LAYER_IDS.DISPLAY}-coffin-corners`,\n      data: pointFeatures,\n      iconAtlas,\n      iconMapping: extendedMapping,\n      getIcon: (d: EditableShape['feature']) => {\n        const shapeId = d.properties?.shapeId;\n        const isSelected = shapeId === selectedShapeId;\n        const isHovered =\n          this.state?.hoverIndex !== undefined &&\n          features.indexOf(d) === this.state.hoverIndex;\n\n        if (isSelected && isHovered) {\n          return COFFIN_CORNERS.SELECTED_HOVER_ICON;\n        }\n        if (isSelected) {\n          return COFFIN_CORNERS.SELECTED_ICON;\n        }\n        return COFFIN_CORNERS.HOVER_ICON;\n      },\n      getSize: COFFIN_CORNERS.SIZE,\n      getPosition: (d: EditableShape['feature']) => {\n        const coords =\n          d.geometry.type === 'Point' ? d.geometry.coordinates : [0, 0];\n        return coords as [number, number];\n      },\n      getPixelOffset: (d: EditableShape['feature']) => {\n        const iconSize =\n          d.properties?.styleProperties?.icon?.size ??\n          MAP_INTERACTION.ICON_SIZE;\n        // Center the coffin corners on the point icon\n        return [-1, -iconSize / 2];\n      },\n      billboard: false,\n      pickable: false,\n      updateTriggers: {\n        getIcon: [selectedShapeId, this.state?.hoverIndex],\n        data: [features, selectedShapeId, this.state?.hoverIndex],\n      },\n    });\n  }\n\n  /**\n   * Extract icon configuration from features in a single pass.\n   * Returns the first icon's atlas and mapping (all shapes share the same atlas).\n   * Uses early return for O(1) best case when first feature has icons.\n   */\n  private getIconConfig(features: EditableShape['feature'][]): {\n    hasIcons: boolean;\n    atlas?: string;\n    mapping?: Record<\n      string,\n      { x: number; y: number; width: number; height: number; mask?: boolean }\n    >;\n  } {\n    for (const f of features) {\n      const icon = f.properties?.styleProperties?.icon;\n      if (icon) {\n        return {\n          hasIcons: true,\n          atlas: icon.atlas,\n          mapping: icon.mapping,\n        };\n      }\n    }\n    return { hasIcons: false };\n  }\n\n  /**\n   * Render main shapes layer\n   */\n  private renderMainLayer(features: EditableShape['feature'][]): GeoJsonLayer {\n    const { pickable, applyBaseOpacity, selectedShapeId } = this.props;\n\n    // Single-pass icon config extraction (O(1) best case with early return)\n    const {\n      hasIcons,\n      atlas: iconAtlas,\n      mapping: iconMapping,\n    } = this.getIconConfig(features);\n\n    return new GeoJsonLayer({\n      id: `${this.props.id}-${SHAPE_LAYER_IDS.DISPLAY}`,\n      // biome-ignore lint/suspicious/noExplicitAny: GeoJsonLayer accepts various feature formats\n      data: features as any,\n\n      // Styling\n      filled: true,\n      stroked: true,\n      getFillColor: (d: EditableShape['feature']) =>\n        getFillColor(d, applyBaseOpacity),\n      getLineColor: getStrokeColor,\n      getLineWidth: (d, info) => {\n        const isHovered = info?.index === this.state?.hoverIndex;\n        return getHoverLineWidth(d, isHovered);\n      },\n      lineWidthUnits: 'pixels',\n      lineWidthMinPixels: MAP_INTERACTION.LINE_WIDTH_MIN_PIXELS,\n      lineWidthMaxPixels: 20,\n\n      // Points - use icons if any feature has icon config, otherwise circles\n      pointType: hasIcons ? 'icon' : 'circle',\n      getPointRadius: (d) => {\n        const iconSize = d.properties?.styleProperties?.icon?.size;\n        return iconSize ?? 2;\n      },\n      pointRadiusUnits: 'pixels',\n\n      // Icon configuration (only used if pointType includes 'icon')\n      ...(hasIcons && iconAtlas ? { iconAtlas } : {}),\n      ...(hasIcons && iconMapping ? { iconMapping } : {}),\n      ...(hasIcons\n        ? {\n            getIcon: (d: EditableShape['feature']) =>\n              d.properties?.styleProperties?.icon?.name ?? 'marker',\n            getIconSize: (d: EditableShape['feature']) => {\n              return (\n                d.properties?.styleProperties?.icon?.size ??\n                MAP_INTERACTION.ICON_SIZE\n              );\n            },\n            getIconColor: getStrokeColor,\n            getIconPixelOffset: (d: EditableShape['feature']) => {\n              const iconSize =\n                d.properties?.styleProperties?.icon?.size ??\n                MAP_INTERACTION.ICON_SIZE;\n              return [-1, -iconSize / 2];\n            },\n            iconBillboard: false,\n          }\n        : {}),\n\n      // Dash pattern support - selected shapes get dotted border\n      extensions: [new PathStyleExtension({ dash: true })],\n      getDashArray: (d: EditableShape['feature']) => {\n        const isSelected = d.properties?.shapeId === selectedShapeId;\n        if (isSelected) {\n          return DASH_ARRAYS.dotted;\n        }\n        return getDashArray(d);\n      },\n\n      // Behavior\n      pickable,\n      autoHighlight: false, // We handle highlighting manually\n      // Note: onClick and onHover are handled via getPickingInfo() override\n\n      // Update triggers\n      updateTriggers: {\n        getFillColor: [features, applyBaseOpacity],\n        getLineColor: [features],\n        getLineWidth: [features, this.state?.hoverIndex],\n        getDashArray: [features, selectedShapeId],\n        getPointRadius: [features],\n        ...(hasIcons\n          ? {\n              getIcon: [features],\n              getIconSize: [features],\n              getIconColor: [features],\n              getIconPixelOffset: [features],\n            }\n          : {}),\n      },\n    });\n  }\n\n  /**\n   * Render labels layer\n   */\n  private renderLabelsLayer(): ReturnType<typeof createShapeLabelLayer> | null {\n    const { showLabels, data, labelOptions } = this.props;\n\n    if (!showLabels) {\n      return null;\n    }\n\n    return createShapeLabelLayer({\n      id: `${this.props.id}-${SHAPE_LAYER_IDS.DISPLAY_LABELS}`,\n      data,\n      labelOptions,\n    });\n  }\n\n  /**\n   * Render all sublayers\n   */\n  renderLayers(): Layer[] {\n    // Compute features once per render cycle for performance\n    const features = this.getFeaturesWithId();\n\n    return [\n      this.renderHighlightLayer(features),\n      this.renderCoffinCornersLayer(features),\n      this.renderMainLayer(features),\n      this.renderLabelsLayer(),\n    ].filter(Boolean) as Layer[];\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,66 @@
+/*
+ * 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 { EditableShape } from "../shared/types.js";
+import { LabelPositionOptions } from "./utils/labels.js";
+import { TextLayer } from "@deck.gl/layers";
+
+//#region src/deckgl/shapes/display-shape-layer/shape-label-layer.d.ts
+/**
+ * Props for creating a shape label layer
+ */
+interface ShapeLabelLayerProps {
+  /** Layer ID (defaults to DISPLAY_LABELS constant) */
+  id?: string;
+  /** Array of shapes to label */
+  data: EditableShape[];
+  /**
+   * Global label positioning options
+   * Per-shape properties in styleProperties take precedence
+   */
+  labelOptions?: LabelPositionOptions;
+}
+/**
+ * Creates a TextLayer for rendering shape labels with intelligent positioning
+ *
+ * ## Features
+ * - **Geometry-aware positioning**: Different defaults for Point, LineString, Polygon, and Circle
+ * - **Three-tier priority system**: Per-shape properties > labelOptions > defaults
+ * - **Coordinate anchoring**: Position labels at start/middle/end (or edge positions for circles)
+ * - **Pixel-based offsets**: Consistent label placement at all zoom levels
+ * - **Text-only styling**: White uppercase text with black outline for legibility
+ * - **Position caching**: Label positions are computed once per shape using a WeakMap cache
+ *
+ * ## Label Positioning Priority
+ * 1. Per-shape `styleProperties` (highest priority)
+ * 2. Global `labelOptions` parameter
+ * 3. Geometry-specific defaults (fallback)
+ *
+ * @param props - Shape label layer configuration
+ * @returns Configured TextLayer instance
+ *
+ * @example
+ * ```tsx
+ * const labelLayer = createShapeLabelLayer({
+ *   id: 'my-labels',
+ *   data: shapes,
+ *   labelOptions: {
+ *     circleLabelCoordinateAnchor: 'top',
+ *     pointLabelOffset: [0, -20],
+ *   },
+ * });
+ * ```
+ */
+declare function createShapeLabelLayer(props: ShapeLabelLayerProps): TextLayer<EditableShape>;
+//#endregion
+export { ShapeLabelLayerProps, createShapeLabelLayer };
+//# sourceMappingURL=shape-label-layer.d.ts.map

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

@@ -0,0 +1,116 @@
+/*
+ * 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 { SHAPE_LAYER_IDS } from "../shared/constants.js";
+import { getLabelPosition2d, getLabelText } from "./utils/labels.js";
+import { TextLayer } from "@deck.gl/layers";
+
+//#region src/deckgl/shapes/display-shape-layer/shape-label-layer.ts
+/**
+* Creates a cached label position getter to avoid computing position multiple times per shape.
+* Uses WeakMap so positions are garbage collected when shapes are removed.
+*/
+function createCachedPositionGetter(labelOptions) {
+	const cache = /* @__PURE__ */ new WeakMap();
+	const getNullable = (shape) => {
+		if (cache.has(shape)) return cache.get(shape) ?? null;
+		const position = getLabelPosition2d(shape, labelOptions);
+		cache.set(shape, position);
+		return position;
+	};
+	const getRequired = (shape) => {
+		const position = getNullable(shape);
+		if (!position) throw new Error("Shape has no valid position - should have been filtered");
+		return position;
+	};
+	return {
+		getRequired,
+		getNullable
+	};
+}
+/**
+* Creates a TextLayer for rendering shape labels with intelligent positioning
+*
+* ## Features
+* - **Geometry-aware positioning**: Different defaults for Point, LineString, Polygon, and Circle
+* - **Three-tier priority system**: Per-shape properties > labelOptions > defaults
+* - **Coordinate anchoring**: Position labels at start/middle/end (or edge positions for circles)
+* - **Pixel-based offsets**: Consistent label placement at all zoom levels
+* - **Text-only styling**: White uppercase text with black outline for legibility
+* - **Position caching**: Label positions are computed once per shape using a WeakMap cache
+*
+* ## Label Positioning Priority
+* 1. Per-shape `styleProperties` (highest priority)
+* 2. Global `labelOptions` parameter
+* 3. Geometry-specific defaults (fallback)
+*
+* @param props - Shape label layer configuration
+* @returns Configured TextLayer instance
+*
+* @example
+* ```tsx
+* const labelLayer = createShapeLabelLayer({
+*   id: 'my-labels',
+*   data: shapes,
+*   labelOptions: {
+*     circleLabelCoordinateAnchor: 'top',
+*     pointLabelOffset: [0, -20],
+*   },
+* });
+* ```
+*/
+function createShapeLabelLayer(props) {
+	const { id = SHAPE_LAYER_IDS.DISPLAY_LABELS, data, labelOptions } = props;
+	const { getRequired, getNullable } = createCachedPositionGetter(labelOptions);
+	return new TextLayer({
+		id,
+		data: data.filter((shape) => getNullable(shape) !== null),
+		getText: getLabelText,
+		getPosition: (d) => getRequired(d).coordinates,
+		getPixelOffset: (d) => getRequired(d).pixelOffset,
+		getTextAnchor: (d) => getRequired(d).textAnchor,
+		getAlignmentBaseline: (d) => getRequired(d).alignmentBaseline,
+		getColor: [
+			255,
+			255,
+			255,
+			255
+		],
+		getSize: 10,
+		getAngle: 0,
+		outlineWidth: 2,
+		outlineColor: [
+			0,
+			0,
+			0,
+			255
+		],
+		background: false,
+		fontFamily: "Roboto MonoVariable, monospace",
+		fontWeight: "bold",
+		fontSettings: { sdf: true },
+		updateTriggers: {
+			getPosition: [labelOptions],
+			getPixelOffset: [labelOptions],
+			getTextAnchor: [labelOptions],
+			getAlignmentBaseline: [labelOptions]
+		},
+		pickable: false
+	});
+}
+
+//#endregion
+export { createShapeLabelLayer };
+//# sourceMappingURL=shape-label-layer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shape-label-layer.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/shape-label-layer.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\n'use client';\n\nimport { TextLayer } from '@deck.gl/layers';\nimport { SHAPE_LAYER_IDS } from '../shared/constants';\nimport {\n  getLabelPosition2d,\n  getLabelText,\n  type LabelPosition2d,\n  type LabelPositionOptions,\n} from './utils/labels';\nimport type { EditableShape } from '../shared/types';\n\n/**\n * Creates a cached label position getter to avoid computing position multiple times per shape.\n * Uses WeakMap so positions are garbage collected when shapes are removed.\n */\nfunction createCachedPositionGetter(\n  labelOptions: LabelPositionOptions | undefined,\n) {\n  const cache = new WeakMap<EditableShape, LabelPosition2d | null>();\n\n  // Returns nullable position for filtering\n  const getNullable = (shape: EditableShape): LabelPosition2d | null => {\n    if (cache.has(shape)) {\n      return cache.get(shape) ?? null;\n    }\n    const position = getLabelPosition2d(shape, labelOptions);\n    cache.set(shape, position);\n    return position;\n  };\n\n  // Returns position, throwing if null (use only after filtering)\n  const getRequired = (shape: EditableShape): LabelPosition2d => {\n    const position = getNullable(shape);\n    if (!position) {\n      throw new Error(\n        'Shape has no valid position - should have been filtered',\n      );\n    }\n    return position;\n  };\n\n  return { getRequired, getNullable };\n}\n\n/**\n * Props for creating a shape label layer\n */\nexport interface ShapeLabelLayerProps {\n  /** Layer ID (defaults to DISPLAY_LABELS constant) */\n  id?: string;\n  /** Array of shapes to label */\n  data: EditableShape[];\n  /**\n   * Global label positioning options\n   * Per-shape properties in styleProperties take precedence\n   */\n  labelOptions?: LabelPositionOptions;\n}\n\n/**\n * Creates a TextLayer for rendering shape labels with intelligent positioning\n *\n * ## Features\n * - **Geometry-aware positioning**: Different defaults for Point, LineString, Polygon, and Circle\n * - **Three-tier priority system**: Per-shape properties > labelOptions > defaults\n * - **Coordinate anchoring**: Position labels at start/middle/end (or edge positions for circles)\n * - **Pixel-based offsets**: Consistent label placement at all zoom levels\n * - **Text-only styling**: White uppercase text with black outline for legibility\n * - **Position caching**: Label positions are computed once per shape using a WeakMap cache\n *\n * ## Label Positioning Priority\n * 1. Per-shape `styleProperties` (highest priority)\n * 2. Global `labelOptions` parameter\n * 3. Geometry-specific defaults (fallback)\n *\n * @param props - Shape label layer configuration\n * @returns Configured TextLayer instance\n *\n * @example\n * ```tsx\n * const labelLayer = createShapeLabelLayer({\n *   id: 'my-labels',\n *   data: shapes,\n *   labelOptions: {\n *     circleLabelCoordinateAnchor: 'top',\n *     pointLabelOffset: [0, -20],\n *   },\n * });\n * ```\n */\nexport function createShapeLabelLayer(\n  props: ShapeLabelLayerProps,\n): TextLayer<EditableShape> {\n  const { id = SHAPE_LAYER_IDS.DISPLAY_LABELS, data, labelOptions } = props;\n\n  // Create cached position getter to avoid computing position 4x per shape\n  const { getRequired, getNullable } = createCachedPositionGetter(labelOptions);\n\n  // Filter out shapes with invalid positions (null coordinates)\n  const validData = data.filter((shape) => getNullable(shape) !== null);\n\n  return new TextLayer<EditableShape>({\n    id,\n    data: validData,\n\n    // Text content - uppercase\n    getText: getLabelText,\n\n    // Position - use cached getter for all position-related properties\n    // getRequired is safe because we filtered out null positions above\n    getPosition: (d: EditableShape) => getRequired(d).coordinates,\n    getPixelOffset: (d: EditableShape) => getRequired(d).pixelOffset,\n    getTextAnchor: (d: EditableShape) => getRequired(d).textAnchor,\n    getAlignmentBaseline: (d: EditableShape) =>\n      getRequired(d).alignmentBaseline,\n\n    // Styling - white text with black outline, no background\n    getColor: [255, 255, 255, 255], // White text\n    getSize: 10,\n    getAngle: 0,\n\n    // Text outline for legibility (black stroke around white text)\n    outlineWidth: 2,\n    outlineColor: [0, 0, 0, 255], // Black outline\n\n    // No background or border\n    background: false,\n\n    // Font\n    fontFamily: 'Roboto MonoVariable, monospace',\n    fontWeight: 'bold',\n    fontSettings: {\n      sdf: true,\n    },\n\n    // Update triggers - tell deck.gl to recalculate when labelOptions change\n    updateTriggers: {\n      getPosition: [labelOptions],\n      getPixelOffset: [labelOptions],\n      getTextAnchor: [labelOptions],\n      getAlignmentBaseline: [labelOptions],\n    },\n\n    // Behavior\n    pickable: false,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAS,2BACP,cACA;CACA,MAAM,wBAAQ,IAAI,SAAgD;CAGlE,MAAM,eAAe,UAAiD;AACpE,MAAI,MAAM,IAAI,MAAM,CAClB,QAAO,MAAM,IAAI,MAAM,IAAI;EAE7B,MAAM,WAAW,mBAAmB,OAAO,aAAa;AACxD,QAAM,IAAI,OAAO,SAAS;AAC1B,SAAO;;CAIT,MAAM,eAAe,UAA0C;EAC7D,MAAM,WAAW,YAAY,MAAM;AACnC,MAAI,CAAC,SACH,OAAM,IAAI,MACR,0DACD;AAEH,SAAO;;AAGT,QAAO;EAAE;EAAa;EAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDrC,SAAgB,sBACd,OAC0B;CAC1B,MAAM,EAAE,KAAK,gBAAgB,gBAAgB,MAAM,iBAAiB;CAGpE,MAAM,EAAE,aAAa,gBAAgB,2BAA2B,aAAa;AAK7E,QAAO,IAAI,UAAyB;EAClC;EACA,MAJgB,KAAK,QAAQ,UAAU,YAAY,MAAM,KAAK,KAAK;EAOnE,SAAS;EAIT,cAAc,MAAqB,YAAY,EAAE,CAAC;EAClD,iBAAiB,MAAqB,YAAY,EAAE,CAAC;EACrD,gBAAgB,MAAqB,YAAY,EAAE,CAAC;EACpD,uBAAuB,MACrB,YAAY,EAAE,CAAC;EAGjB,UAAU;GAAC;GAAK;GAAK;GAAK;GAAI;EAC9B,SAAS;EACT,UAAU;EAGV,cAAc;EACd,cAAc;GAAC;GAAG;GAAG;GAAG;GAAI;EAG5B,YAAY;EAGZ,YAAY;EACZ,YAAY;EACZ,cAAc,EACZ,KAAK,MACN;EAGD,gBAAgB;GACd,aAAa,CAAC,aAAa;GAC3B,gBAAgB,CAAC,aAAa;GAC9B,eAAe,CAAC,aAAa;GAC7B,sBAAsB,CAAC,aAAa;GACrC;EAGD,UAAU;EACX,CAAC"}

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

@@ -0,0 +1,87 @@
+/*
+ * 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 { ShapeId } from "../shared/types.js";
+import { UniqueId } from "@accelint/core";
+
+//#region src/deckgl/shapes/display-shape-layer/store.d.ts
+/**
+ * Creates or retrieves a cached subscription function for a given mapId.
+ * Uses a fan-out pattern: 1 bus listener -> N React subscribers.
+ * Automatically cleans up selection state when the last subscriber unsubscribes.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A subscription function for useSyncExternalStore
+ */
+declare function getOrCreateSubscription(mapId: UniqueId): (onStoreChange: () => void) => () => void;
+/**
+ * Creates or retrieves a cached snapshot function for a given mapId.
+ * The selection ID returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A snapshot function for useSyncExternalStore
+ */
+declare function getOrCreateSnapshot(mapId: UniqueId): () => ShapeId | undefined;
+/**
+ * Creates or retrieves a cached server snapshot function for a given mapId.
+ * Server snapshots always return undefined since selection state is client-only.
+ * Required for SSR/RSC compatibility with useSyncExternalStore.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A server snapshot function for useSyncExternalStore
+ */
+declare function getOrCreateServerSnapshot(mapId: UniqueId): () => ShapeId | undefined;
+/**
+ * Creates or retrieves a cached setSelectedId function for a given mapId.
+ * This maintains referential stability for the function reference.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A setSelectedId function for this instance
+ */
+declare function getOrCreateSetSelectedId(mapId: UniqueId): (id: ShapeId | undefined) => void;
+/**
+ * Creates or retrieves a cached clearSelection function for a given mapId.
+ * This maintains referential stability for the function reference.
+ *
+ * Note: This always emits a deselected event, even if nothing is currently selected.
+ * This matches the original behavior and allows consumers to use clearSelection
+ * as a "force deselect" without needing to check selection state first.
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns A clearSelection function for this instance
+ */
+declare function getOrCreateClearSelection(mapId: UniqueId): () => void;
+/**
+ * Get the current selected shape ID for a given map instance (direct access, not reactive).
+ * @internal - For internal map-toolkit use only
+ *
+ * @param mapId - The unique identifier for the map instance
+ * @returns The currently selected shape ID, or undefined
+ */
+declare function getSelectedShapeId(mapId: UniqueId): ShapeId | undefined;
+/**
+ * Manually clear all selection state for a specific mapId.
+ * This is typically not needed as cleanup happens automatically when all subscribers unmount.
+ * Use this only in advanced scenarios where manual cleanup is required.
+ *
+ * @param mapId - The unique identifier for the map instance to clear
+ *
+ * @example
+ * ```tsx
+ * // Manual cleanup (rarely needed)
+ * clearSelectionState('my-map-instance');
+ * ```
+ */
+declare function clearSelectionState(mapId: UniqueId): void;
+//#endregion
+export { clearSelectionState, getOrCreateClearSelection, getOrCreateServerSnapshot, getOrCreateSetSelectedId, getOrCreateSnapshot, getOrCreateSubscription, getSelectedShapeId };
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1,316 @@
+/*
+ * 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 "../../base-map/events.js";
+import { ShapeEvents } from "../shared/events.js";
+import { Broadcast } from "@accelint/bus";
+
+//#region src/deckgl/shapes/display-shape-layer/store.ts
+/**
+* Shape Selection Store
+*
+* This module provides a store pattern for managing shape selection state,
+* designed to work with React's `useSyncExternalStore` hook.
+*
+* ## Architecture
+*
+* The store uses a fan-out pattern similar to `map-cursor/store.ts` and `map-mode/store.ts`:
+* - **1 bus listener per mapId** - Regardless of how many React components subscribe
+* - **N React subscribers** - Each component gets notified via `useSyncExternalStore`
+* - **Automatic cleanup** - Bus listeners are removed when the last subscriber unmounts
+*
+* ## Why This Pattern?
+*
+* Without this pattern, using `useOn` directly in each React component would
+* create N bus listeners for N components subscribing to the same events.
+* The fan-out pattern ensures exactly 1 bus listener per mapId, regardless
+* of how many React components need the state. This also provides proper
+* cleanup semantics that prevent listener accumulation during HMR.
+*
+* ## Usage
+*
+* This module is internal to `useShapeSelection`. Use the hook instead:
+*
+* ```tsx
+* import { useShapeSelection } from '@accelint/map-toolkit/deckgl/shapes';
+*
+* const { selectedId, setSelectedId, clearSelection } = useShapeSelection(mapId);
+* ```
+*
+* @module
+*/
+/**
+* Typed event bus instances for shape and map events
+*/
+const shapeBus = Broadcast.getInstance();
+const mapBus = Broadcast.getInstance();
+/**
+* Store for shape selection state keyed by mapId
+*/
+const selectionStore = /* @__PURE__ */ new Map();
+/**
+* Track React component subscribers per mapId (for fan-out notifications).
+* Each Set contains onStoreChange callbacks from useSyncExternalStore.
+*/
+const componentSubscribers = /* @__PURE__ */ new Map();
+/**
+* Cache of bus unsubscribe functions (1 per mapId).
+* This ensures we only have one bus listener per map instance, regardless of
+* how many React components subscribe to it.
+*/
+const busUnsubscribers = /* @__PURE__ */ new Map();
+/**
+* Cache of subscription functions per mapId to avoid recreating on every render
+*/
+const subscriptionCache = /* @__PURE__ */ new Map();
+/**
+* Cache of snapshot functions per mapId to maintain referential stability
+*/
+const snapshotCache = /* @__PURE__ */ new Map();
+/**
+* Cache of server snapshot functions per mapId to maintain referential stability.
+* Server snapshots always return undefined since selection state is client-only.
+*/
+const serverSnapshotCache = /* @__PURE__ */ new Map();
+/**
+* Cache of setSelectedId functions per mapId to maintain referential stability
+*/
+const setSelectedIdCache = /* @__PURE__ */ new Map();
+/**
+* Cache of clearSelection functions per mapId to maintain referential stability
+*/
+const clearSelectionCache = /* @__PURE__ */ new Map();
+/**
+* All state caches that need cleanup when an instance is removed
+*/
+const stateCaches = [
+	selectionStore,
+	componentSubscribers,
+	subscriptionCache,
+	snapshotCache,
+	serverSnapshotCache,
+	setSelectedIdCache,
+	clearSelectionCache
+];
+/**
+* Clear all cached state for a given mapId
+*/
+function clearAllCaches(mapId) {
+	for (const cache of stateCaches) cache.delete(mapId);
+}
+/**
+* Get or create selection state for a given mapId
+*/
+function getOrCreateState(mapId) {
+	if (!selectionStore.has(mapId)) selectionStore.set(mapId, { selectedId: void 0 });
+	return selectionStore.get(mapId);
+}
+/**
+* Get current selection snapshot for a given map instance (for useSyncExternalStore)
+*/
+function getSnapshot(mapId) {
+	return selectionStore.get(mapId)?.selectedId;
+}
+/**
+* Notify all React subscribers for a given mapId
+*/
+function notifySubscribers(mapId) {
+	const subscribers = componentSubscribers.get(mapId);
+	if (subscribers) for (const onStoreChange of subscribers) onStoreChange();
+}
+/**
+* Ensures a single bus listener exists for the given mapId.
+* All React subscribers will be notified via fan-out when the bus events fire.
+* This prevents creating N bus listeners for N React components.
+*
+* @param mapId - The unique identifier for the map instance
+*/
+function ensureBusListener(mapId) {
+	if (busUnsubscribers.has(mapId)) return;
+	const state = getOrCreateState(mapId);
+	const unsubSelected = shapeBus.on(ShapeEvents.selected, (event) => {
+		if (event.payload.mapId !== mapId) return;
+		const previousId = state.selectedId;
+		state.selectedId = event.payload.shapeId;
+		if (previousId !== state.selectedId) notifySubscribers(mapId);
+	});
+	const unsubDeselected = shapeBus.on(ShapeEvents.deselected, (event) => {
+		if (event.payload.mapId !== mapId) return;
+		const previousId = state.selectedId;
+		state.selectedId = void 0;
+		if (previousId !== state.selectedId) notifySubscribers(mapId);
+	});
+	const unsubClick = mapBus.on(MapEvents.click, (event) => {
+		if (state.selectedId && event.payload.id === mapId && event.payload.info.index === -1) shapeBus.emit(ShapeEvents.deselected, { mapId });
+	});
+	busUnsubscribers.set(mapId, () => {
+		unsubSelected();
+		unsubDeselected();
+		unsubClick();
+	});
+}
+/**
+* Cleans up the bus listener if no React subscribers remain.
+*
+* @param mapId - The unique identifier for the map instance
+*/
+function cleanupBusListenerIfNeeded(mapId) {
+	const subscribers = componentSubscribers.get(mapId);
+	if (!subscribers || subscribers.size === 0) {
+		const unsub = busUnsubscribers.get(mapId);
+		if (unsub) {
+			unsub();
+			busUnsubscribers.delete(mapId);
+		}
+		clearAllCaches(mapId);
+	}
+}
+/**
+* Creates or retrieves a cached subscription function for a given mapId.
+* Uses a fan-out pattern: 1 bus listener -> N React subscribers.
+* Automatically cleans up selection state when the last subscriber unsubscribes.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A subscription function for useSyncExternalStore
+*/
+function getOrCreateSubscription(mapId) {
+	let subscription = subscriptionCache.get(mapId);
+	if (!subscription) {
+		subscription = (onStoreChange) => {
+			getOrCreateState(mapId);
+			ensureBusListener(mapId);
+			let subscriberSet = componentSubscribers.get(mapId);
+			if (!subscriberSet) {
+				subscriberSet = /* @__PURE__ */ new Set();
+				componentSubscribers.set(mapId, subscriberSet);
+			}
+			subscriberSet.add(onStoreChange);
+			return () => {
+				const currentSubscriberSet = componentSubscribers.get(mapId);
+				if (currentSubscriberSet) currentSubscriberSet.delete(onStoreChange);
+				cleanupBusListenerIfNeeded(mapId);
+			};
+		};
+		subscriptionCache.set(mapId, subscription);
+	}
+	return subscription;
+}
+/**
+* Creates or retrieves a cached snapshot function for a given mapId.
+* The selection ID returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A snapshot function for useSyncExternalStore
+*/
+function getOrCreateSnapshot(mapId) {
+	let snapshot = snapshotCache.get(mapId);
+	if (!snapshot) {
+		snapshot = () => getSnapshot(mapId);
+		snapshotCache.set(mapId, snapshot);
+	}
+	return snapshot;
+}
+/**
+* Creates or retrieves a cached server snapshot function for a given mapId.
+* Server snapshots always return undefined since selection state is client-only.
+* Required for SSR/RSC compatibility with useSyncExternalStore.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A server snapshot function for useSyncExternalStore
+*/
+function getOrCreateServerSnapshot(mapId) {
+	let serverSnapshot = serverSnapshotCache.get(mapId);
+	if (!serverSnapshot) {
+		serverSnapshot = () => void 0;
+		serverSnapshotCache.set(mapId, serverSnapshot);
+	}
+	return serverSnapshot;
+}
+/**
+* Creates or retrieves a cached setSelectedId function for a given mapId.
+* This maintains referential stability for the function reference.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A setSelectedId function for this instance
+*/
+function getOrCreateSetSelectedId(mapId) {
+	let setSelectedId = setSelectedIdCache.get(mapId);
+	if (!setSelectedId) {
+		setSelectedId = (id) => {
+			const previousId = getOrCreateState(mapId).selectedId;
+			if (id === void 0 && previousId !== void 0) shapeBus.emit(ShapeEvents.deselected, { mapId });
+			else if (id !== void 0 && previousId !== id) shapeBus.emit(ShapeEvents.selected, {
+				shapeId: id,
+				mapId
+			});
+		};
+		setSelectedIdCache.set(mapId, setSelectedId);
+	}
+	return setSelectedId;
+}
+/**
+* Creates or retrieves a cached clearSelection function for a given mapId.
+* This maintains referential stability for the function reference.
+*
+* Note: This always emits a deselected event, even if nothing is currently selected.
+* This matches the original behavior and allows consumers to use clearSelection
+* as a "force deselect" without needing to check selection state first.
+*
+* @param mapId - The unique identifier for the map instance
+* @returns A clearSelection function for this instance
+*/
+function getOrCreateClearSelection(mapId) {
+	let clearSelection = clearSelectionCache.get(mapId);
+	if (!clearSelection) {
+		clearSelection = () => {
+			shapeBus.emit(ShapeEvents.deselected, { mapId });
+		};
+		clearSelectionCache.set(mapId, clearSelection);
+	}
+	return clearSelection;
+}
+/**
+* Get the current selected shape ID for a given map instance (direct access, not reactive).
+* @internal - For internal map-toolkit use only
+*
+* @param mapId - The unique identifier for the map instance
+* @returns The currently selected shape ID, or undefined
+*/
+function getSelectedShapeId(mapId) {
+	return getSnapshot(mapId);
+}
+/**
+* Manually clear all selection state for a specific mapId.
+* This is typically not needed as cleanup happens automatically when all subscribers unmount.
+* Use this only in advanced scenarios where manual cleanup is required.
+*
+* @param mapId - The unique identifier for the map instance to clear
+*
+* @example
+* ```tsx
+* // Manual cleanup (rarely needed)
+* clearSelectionState('my-map-instance');
+* ```
+*/
+function clearSelectionState(mapId) {
+	const unsub = busUnsubscribers.get(mapId);
+	if (unsub) {
+		unsub();
+		busUnsubscribers.delete(mapId);
+	}
+	clearAllCaches(mapId);
+}
+
+//#endregion
+export { clearSelectionState, getOrCreateClearSelection, getOrCreateServerSnapshot, getOrCreateSetSelectedId, getOrCreateSnapshot, getOrCreateSubscription, getSelectedShapeId };
+//# sourceMappingURL=store.js.map