@accelint/map-toolkit 1.2.0 → 1.3.0

package/dist/deckgl/text-layer/index.d.ts

@@ -15,7 +15,16 @@ import { TextLayer as TextLayer$1, TextLayerProps as TextLayerProps$1 } from "@d
 import { LiteralUnion } from "type-fest";
 
 //#region src/deckgl/text-layer/index.d.ts
+/**
+ * Props for TextLayer component.
+ * Extends Deck.gl's TextLayerProps with enhanced character set support.
+ */
 interface TextLayerProps<TData = unknown> extends TextLayerProps$1<TData> {
+  /**
+   * Character set to use for text rendering.
+   * Can be a predefined CHARACTER_SETS key or a custom string of characters.
+   * Defaults to CHARACTER_SETS.EXPANDED for international text support.
+   */
   characterSet?: LiteralUnion<CharacterSetsKeys, string>;
 }
 /**
@@ -30,6 +39,62 @@ interface TextLayerProps<TData = unknown> extends TextLayerProps$1<TData> {
  * Can be used directly with Deck.gl or as a JSX element with React Fiber:
  * - React Fiber: `<textLayer id="text" data={[...]} ... />`
  * - Direct: `new TextLayer({ id: 'text', data: [...], ... })`
+ *
+ * @example
+ * Direct Deck.gl usage:
+ * ```typescript
+ * import { Deck } from '@deck.gl/core';
+ * import { TextLayer } from '@accelint/map-toolkit/deckgl/text-layer';
+ *
+ * const layer = new TextLayer({
+ *   id: 'text-labels',
+ *   data: [
+ *     { position: [-122.4, 37.74], text: 'San Francisco' },
+ *     { position: [-118.2, 34.05], text: 'Los Angeles' },
+ *   ],
+ *   getText: d => d.text,
+ *   getPosition: d => d.position,
+ *   getSize: 14,
+ *   fontWeight: 600,
+ *   outlineWidth: 2,
+ * });
+ *
+ * new Deck({
+ *   initialViewState: { longitude: -120, latitude: 36, zoom: 6 },
+ *   controller: true,
+ *   layers: [layer],
+ * });
+ * ```
+ *
+ * @example
+ * React Fiber usage:
+ * ```tsx
+ * import '@accelint/map-toolkit/deckgl/text-layer/fiber';
+ * import { BaseMap } from '@accelint/map-toolkit/deckgl';
+ * import { View } from '@deckgl-fiber-renderer/dom';
+ *
+ * function MapWithLabels() {
+ *   const cities = [
+ *     { position: [-122.4, 37.74], text: 'San Francisco' },
+ *     { position: [-118.2, 34.05], text: 'Los Angeles' },
+ *   ];
+ *
+ *   return (
+ *     <BaseMap id="map" className="w-full h-full">
+ *       <View id="main" controller />
+ *       <textLayer
+ *         id="city-labels"
+ *         data={cities}
+ *         getText={d => d.text}
+ *         getPosition={d => d.position}
+ *         getSize={14}
+ *         fontWeight={600}
+ *         outlineWidth={2}
+ *       />
+ *     </BaseMap>
+ *   );
+ * }
+ * ```
  */
 declare class TextLayer<TData = unknown> extends TextLayer$1<TData> {
   static CHARACTER_SETS: Readonly<{

package/dist/deckgl/text-layer/index.js

@@ -28,6 +28,62 @@ import { TextLayer as TextLayer$1 } from "@deck.gl/layers";
 * Can be used directly with Deck.gl or as a JSX element with React Fiber:
 * - React Fiber: `<textLayer id="text" data={[...]} ... />`
 * - Direct: `new TextLayer({ id: 'text', data: [...], ... })`
+*
+* @example
+* Direct Deck.gl usage:
+* ```typescript
+* import { Deck } from '@deck.gl/core';
+* import { TextLayer } from '@accelint/map-toolkit/deckgl/text-layer';
+*
+* const layer = new TextLayer({
+*   id: 'text-labels',
+*   data: [
+*     { position: [-122.4, 37.74], text: 'San Francisco' },
+*     { position: [-118.2, 34.05], text: 'Los Angeles' },
+*   ],
+*   getText: d => d.text,
+*   getPosition: d => d.position,
+*   getSize: 14,
+*   fontWeight: 600,
+*   outlineWidth: 2,
+* });
+*
+* new Deck({
+*   initialViewState: { longitude: -120, latitude: 36, zoom: 6 },
+*   controller: true,
+*   layers: [layer],
+* });
+* ```
+*
+* @example
+* React Fiber usage:
+* ```tsx
+* import '@accelint/map-toolkit/deckgl/text-layer/fiber';
+* import { BaseMap } from '@accelint/map-toolkit/deckgl';
+* import { View } from '@deckgl-fiber-renderer/dom';
+*
+* function MapWithLabels() {
+*   const cities = [
+*     { position: [-122.4, 37.74], text: 'San Francisco' },
+*     { position: [-118.2, 34.05], text: 'Los Angeles' },
+*   ];
+*
+*   return (
+*     <BaseMap id="map" className="w-full h-full">
+*       <View id="main" controller />
+*       <textLayer
+*         id="city-labels"
+*         data={cities}
+*         getText={d => d.text}
+*         getPosition={d => d.position}
+*         getSize={14}
+*         fontWeight={600}
+*         outlineWidth={2}
+*       />
+*     </BaseMap>
+*   );
+* }
+* ```
 */
 var TextLayer = class extends TextLayer$1 {
 	static CHARACTER_SETS = CHARACTER_SETS;

package/dist/deckgl/text-layer/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["DglTextLayer"],"sources":["../../../src/deckgl/text-layer/index.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 {\n  TextLayer as DglTextLayer,\n  type TextLayerProps as DglTextLayerProps,\n} from '@deck.gl/layers';\nimport { CHARACTER_SETS, type CharacterSetsKeys } from './character-sets.js';\nimport { defaultSettings } from './default-settings.js';\nimport type { LiteralUnion } from 'type-fest';\n\nexport interface TextLayerProps<TData = unknown>\n  extends DglTextLayerProps<TData> {\n  // A union type that preserves autocompletion for CharacterSetsKeys while allowing any string.\n  characterSet?: LiteralUnion<CharacterSetsKeys, string>;\n}\n\n/**\n * A styled text layer that extends Deck.gl's TextLayer with enhanced styling capabilities.\n *\n * This layer provides:\n * - Customizable font styling (size, weight, family, line height)\n * - Text outline support\n * - Extended character set support\n * - Consistent styling based on design specifications\n *\n * Can be used directly with Deck.gl or as a JSX element with React Fiber:\n * - React Fiber: `<textLayer id=\"text\" data={[...]} ... />`\n * - Direct: `new TextLayer({ id: 'text', data: [...], ... })`\n */\nexport class TextLayer<TData = unknown> extends DglTextLayer<TData> {\n  static CHARACTER_SETS = CHARACTER_SETS;\n\n  static override layerName = 'textLayer';\n\n  constructor(props: TextLayerProps<TData>) {\n    const {\n      characterSet = CHARACTER_SETS.EXPANDED,\n      fontSettings,\n      ...rest\n    } = props;\n\n    super({\n      // set opinionated defaults\n      ...defaultSettings,\n\n      // user props override defaults\n      ...rest,\n\n      // handle special characterSet logic\n      characterSet:\n        CHARACTER_SETS[characterSet as CharacterSetsKeys] ?? characterSet,\n\n      fontSettings: {\n        // merge fontSettings\n        ...defaultSettings.fontSettings,\n\n        // user props override defaults\n        ...fontSettings,\n      },\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAa,YAAb,cAAgDA,YAAoB;CAClE,OAAO,iBAAiB;CAExB,OAAgB,YAAY;CAE5B,YAAY,OAA8B;EACxC,MAAM,EACJ,eAAe,eAAe,UAC9B,cACA,GAAG,SACD;AAEJ,QAAM;GAEJ,GAAG;GAGH,GAAG;GAGH,cACE,eAAe,iBAAsC;GAEvD,cAAc;IAEZ,GAAG,gBAAgB;IAGnB,GAAG;IACJ;GACF,CAAC"}
+{"version":3,"file":"index.js","names":["DglTextLayer"],"sources":["../../../src/deckgl/text-layer/index.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 {\n  TextLayer as DglTextLayer,\n  type TextLayerProps as DglTextLayerProps,\n} from '@deck.gl/layers';\nimport { CHARACTER_SETS, type CharacterSetsKeys } from './character-sets.js';\nimport { defaultSettings } from './default-settings.js';\nimport type { LiteralUnion } from 'type-fest';\n\n/**\n * Props for TextLayer component.\n * Extends Deck.gl's TextLayerProps with enhanced character set support.\n */\nexport interface TextLayerProps<TData = unknown>\n  extends DglTextLayerProps<TData> {\n  /**\n   * Character set to use for text rendering.\n   * Can be a predefined CHARACTER_SETS key or a custom string of characters.\n   * Defaults to CHARACTER_SETS.EXPANDED for international text support.\n   */\n  characterSet?: LiteralUnion<CharacterSetsKeys, string>;\n}\n\n/**\n * A styled text layer that extends Deck.gl's TextLayer with enhanced styling capabilities.\n *\n * This layer provides:\n * - Customizable font styling (size, weight, family, line height)\n * - Text outline support\n * - Extended character set support\n * - Consistent styling based on design specifications\n *\n * Can be used directly with Deck.gl or as a JSX element with React Fiber:\n * - React Fiber: `<textLayer id=\"text\" data={[...]} ... />`\n * - Direct: `new TextLayer({ id: 'text', data: [...], ... })`\n *\n * @example\n * Direct Deck.gl usage:\n * ```typescript\n * import { Deck } from '@deck.gl/core';\n * import { TextLayer } from '@accelint/map-toolkit/deckgl/text-layer';\n *\n * const layer = new TextLayer({\n *   id: 'text-labels',\n *   data: [\n *     { position: [-122.4, 37.74], text: 'San Francisco' },\n *     { position: [-118.2, 34.05], text: 'Los Angeles' },\n *   ],\n *   getText: d => d.text,\n *   getPosition: d => d.position,\n *   getSize: 14,\n *   fontWeight: 600,\n *   outlineWidth: 2,\n * });\n *\n * new Deck({\n *   initialViewState: { longitude: -120, latitude: 36, zoom: 6 },\n *   controller: true,\n *   layers: [layer],\n * });\n * ```\n *\n * @example\n * React Fiber usage:\n * ```tsx\n * import '@accelint/map-toolkit/deckgl/text-layer/fiber';\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { View } from '@deckgl-fiber-renderer/dom';\n *\n * function MapWithLabels() {\n *   const cities = [\n *     { position: [-122.4, 37.74], text: 'San Francisco' },\n *     { position: [-118.2, 34.05], text: 'Los Angeles' },\n *   ];\n *\n *   return (\n *     <BaseMap id=\"map\" className=\"w-full h-full\">\n *       <View id=\"main\" controller />\n *       <textLayer\n *         id=\"city-labels\"\n *         data={cities}\n *         getText={d => d.text}\n *         getPosition={d => d.position}\n *         getSize={14}\n *         fontWeight={600}\n *         outlineWidth={2}\n *       />\n *     </BaseMap>\n *   );\n * }\n * ```\n */\nexport class TextLayer<TData = unknown> extends DglTextLayer<TData> {\n  static CHARACTER_SETS = CHARACTER_SETS;\n\n  static override layerName = 'textLayer';\n\n  constructor(props: TextLayerProps<TData>) {\n    const {\n      characterSet = CHARACTER_SETS.EXPANDED,\n      fontSettings,\n      ...rest\n    } = props;\n\n    super({\n      // set opinionated defaults\n      ...defaultSettings,\n\n      // user props override defaults\n      ...rest,\n\n      // handle special characterSet logic\n      characterSet:\n        CHARACTER_SETS[characterSet as CharacterSetsKeys] ?? characterSet,\n\n      fontSettings: {\n        // merge fontSettings\n        ...defaultSettings.fontSettings,\n\n        // user props override defaults\n        ...fontSettings,\n      },\n    });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuGA,IAAa,YAAb,cAAgDA,YAAoB;CAClE,OAAO,iBAAiB;CAExB,OAAgB,YAAY;CAE5B,YAAY,OAA8B;EACxC,MAAM,EACJ,eAAe,eAAe,UAC9B,cACA,GAAG,SACD;AAEJ,QAAM;GAEJ,GAAG;GAGH,GAAG;GAGH,cACE,eAAe,iBAAsC;GAEvD,cAAc;IAEZ,GAAG,gBAAgB;IAGnB,GAAG;IACJ;GACF,CAAC"}

package/dist/map-cursor/events.d.ts

@@ -2,6 +2,25 @@
 /**
  * Event keys for map cursor state changes.
  * These events are used for communication between cursor stores and consumers.
+ *
+ * @example
+ * ```typescript
+ * import { Broadcast } from '@accelint/bus';
+ * import { MapCursorEvents } from '@accelint/map-toolkit/map-cursor';
+ * import type { MapCursorEventType } from '@accelint/map-toolkit/map-cursor';
+ *
+ * const bus = Broadcast.getInstance<MapCursorEventType>();
+ *
+ * // Listen for cursor changes
+ * bus.on(MapCursorEvents.changed, (event) => {
+ *   console.log('Cursor changed to:', event.payload.currentCursor);
+ * });
+ *
+ * // Listen for rejections
+ * bus.on(MapCursorEvents.rejected, (event) => {
+ *   console.warn('Cursor change rejected:', event.payload.reason);
+ * });
+ * ```
  */
 declare const MapCursorEvents: {
   /** Emitted when a component requests a cursor change */

package/dist/map-cursor/events.js

@@ -15,6 +15,25 @@
 /**
 * Event keys for map cursor state changes.
 * These events are used for communication between cursor stores and consumers.
+*
+* @example
+* ```typescript
+* import { Broadcast } from '@accelint/bus';
+* import { MapCursorEvents } from '@accelint/map-toolkit/map-cursor';
+* import type { MapCursorEventType } from '@accelint/map-toolkit/map-cursor';
+*
+* const bus = Broadcast.getInstance<MapCursorEventType>();
+*
+* // Listen for cursor changes
+* bus.on(MapCursorEvents.changed, (event) => {
+*   console.log('Cursor changed to:', event.payload.currentCursor);
+* });
+*
+* // Listen for rejections
+* bus.on(MapCursorEvents.rejected, (event) => {
+*   console.warn('Cursor change rejected:', event.payload.reason);
+* });
+* ```
 */
 const MapCursorEvents = {
 	changeRequest: "cursor:change-request",

package/dist/map-cursor/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","names":[],"sources":["../../src/map-cursor/events.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Event keys for map cursor state changes.\n * These events are used for communication between cursor stores and consumers.\n */\nexport const MapCursorEvents = {\n  /** Emitted when a component requests a cursor change */\n  changeRequest: 'cursor:change-request',\n  /** Emitted when the cursor has been changed */\n  changed: 'cursor:changed',\n  /** Emitted when a cursor change request is rejected */\n  rejected: 'cursor:rejected',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgBA,MAAa,kBAAkB;CAE7B,eAAe;CAEf,SAAS;CAET,UAAU;CACX"}
+{"version":3,"file":"events.js","names":[],"sources":["../../src/map-cursor/events.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Event keys for map cursor state changes.\n * These events are used for communication between cursor stores and consumers.\n *\n * @example\n * ```typescript\n * import { Broadcast } from '@accelint/bus';\n * import { MapCursorEvents } from '@accelint/map-toolkit/map-cursor';\n * import type { MapCursorEventType } from '@accelint/map-toolkit/map-cursor';\n *\n * const bus = Broadcast.getInstance<MapCursorEventType>();\n *\n * // Listen for cursor changes\n * bus.on(MapCursorEvents.changed, (event) => {\n *   console.log('Cursor changed to:', event.payload.currentCursor);\n * });\n *\n * // Listen for rejections\n * bus.on(MapCursorEvents.rejected, (event) => {\n *   console.warn('Cursor change rejected:', event.payload.reason);\n * });\n * ```\n */\nexport const MapCursorEvents = {\n  /** Emitted when a component requests a cursor change */\n  changeRequest: 'cursor:change-request',\n  /** Emitted when the cursor has been changed */\n  changed: 'cursor:changed',\n  /** Emitted when a cursor change request is rejected */\n  rejected: 'cursor:rejected',\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,MAAa,kBAAkB;CAE7B,eAAe;CAEf,SAAS;CAET,UAAU;CACX"}

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

@@ -40,7 +40,21 @@ type CursorActions = {
  */
 declare const cursorStore: MapStore<CursorState, CursorActions>;
 /**
- * Get effective cursor (computed from state)
+ * Get effective cursor value for a map instance.
+ *
+ * Computes the effective cursor from the current state by applying
+ * the priority system (mode owner > most recent > default).
+ *
+ * @param mapId - Unique identifier for the map instance
+ * @returns The effective cursor to display
+ *
+ * @example
+ * ```typescript
+ * import { getCursor } from '@accelint/map-toolkit/map-cursor';
+ *
+ * const currentCursor = getCursor(mapId);
+ * console.log('Current cursor:', currentCursor); // 'default', 'pointer', etc.
+ * ```
  */
 declare function getCursor(mapId: UniqueId): CSSCursorType;
 /**
@@ -53,10 +67,28 @@ declare function getCursor(mapId: UniqueId): CSSCursorType;
  * - Better ergonomics for consumers
  *
  * This hook exists for internal composition (used by useMapCursor).
+ *
+ * @param mapId - Unique identifier for the map instance
+ * @returns The effective cursor to display
  */
 declare function useCursor(mapId: UniqueId): CSSCursorType;
 /**
- * Clear cursor state
+ * Clear cursor state for a specific map instance.
+ *
+ * Removes all cursor ownership data and resets to default state.
+ * This is typically not needed as cleanup happens automatically.
+ * Use only in advanced scenarios where manual cleanup is required.
+ *
+ * @param mapId - Unique identifier for the map instance to clear
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * import { clearCursorState } from '@accelint/map-toolkit/map-cursor';
+ *
+ * // Manual cleanup when destroying a map
+ * clearCursorState(mapId);
+ * ```
  */
 declare function clearCursorState(mapId: UniqueId): void;
 //#endregion

package/dist/map-cursor/store.js

@@ -73,7 +73,16 @@ function isRegisteredOwner(mapId, owner) {
 	return isRegisteredModeOwnerFn?.(mapId, owner) ?? false;
 }
 /**
-* Calculate effective cursor based on priority
+* Calculate effective cursor based on priority.
+*
+* Priority order:
+* 1. Mode owner's cursor (if mode is owned)
+* 2. Most recent cursor request (if owner still has entry)
+* 3. Default cursor
+*
+* @param mapId - Unique identifier for the map instance
+* @param state - Current cursor state
+* @returns The effective cursor to display
 */
 function getEffectiveCursor(mapId, state) {
 	const modeOwner = getModeOwner?.(mapId);
@@ -191,7 +200,21 @@ const cursorStore = createMapStore({
 	}
 });
 /**
-* Get effective cursor (computed from state)
+* Get effective cursor value for a map instance.
+*
+* Computes the effective cursor from the current state by applying
+* the priority system (mode owner > most recent > default).
+*
+* @param mapId - Unique identifier for the map instance
+* @returns The effective cursor to display
+*
+* @example
+* ```typescript
+* import { getCursor } from '@accelint/map-toolkit/map-cursor';
+*
+* const currentCursor = getCursor(mapId);
+* console.log('Current cursor:', currentCursor); // 'default', 'pointer', etc.
+* ```
 */
 function getCursor(mapId) {
 	return getEffectiveCursor(mapId, cursorStore.get(mapId));
@@ -206,12 +229,30 @@ function getCursor(mapId) {
 * - Better ergonomics for consumers
 *
 * This hook exists for internal composition (used by useMapCursor).
+*
+* @param mapId - Unique identifier for the map instance
+* @returns The effective cursor to display
 */
 function useCursor(mapId) {
 	return cursorStore.useSelector(mapId, (state) => getEffectiveCursor(mapId, state));
 }
 /**
-* Clear cursor state
+* Clear cursor state for a specific map instance.
+*
+* Removes all cursor ownership data and resets to default state.
+* This is typically not needed as cleanup happens automatically.
+* Use only in advanced scenarios where manual cleanup is required.
+*
+* @param mapId - Unique identifier for the map instance to clear
+* @returns void
+*
+* @example
+* ```typescript
+* import { clearCursorState } from '@accelint/map-toolkit/map-cursor';
+*
+* // Manual cleanup when destroying a map
+* clearCursorState(mapId);
+* ```
 */
 function clearCursorState(mapId) {
 	cursorStore.clear(mapId);

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

@@ -1 +1 @@
-{"version":3,"file":"store.js","names":["DEFAULT_CURSOR: CSSCursorType","getModeOwnerFn: ((mapId: UniqueId) => string | undefined) | null","isRegisteredModeOwnerFn:\n  | ((mapId: UniqueId, owner: string) => boolean)\n  | null","importPromise: Promise<void> | null","updates: Partial<CursorState>","newState: CursorState"],"sources":["../../src/map-cursor/store.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Map Cursor Store\n *\n * Manages cursor state with ownership-based priority.\n *\n * Priority order:\n * 1. Mode owner's cursor (if mode is owned)\n * 2. Most recent cursor request\n * 3. Default cursor\n *\n * @example\n * ```tsx\n * import { cursorStore } from '@accelint/map-toolkit/map-cursor';\n *\n * function MapContainer({ mapId }) {\n *   const cursor = cursorStore.useSelector(mapId, (s) => getEffectiveCursor(mapId, s));\n *   return <div style={{ cursor }}>...</div>;\n * }\n *\n * // Request cursor change from a layer:\n * cursorStore.actions(mapId).requestCursorChange('crosshair', 'draw-layer');\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { MapModeEvents } from '../map-mode/events';\nimport { createMapStore, mapDelete, mapSet } from '../shared/create-map-store';\nimport { MapCursorEvents } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { ModeChangedEvent } from '../map-mode/types';\nimport type { CSSCursorType, MapCursorEventType } from './types';\n\nconst DEFAULT_CURSOR: CSSCursorType = 'default';\n\n/**\n * State shape for map cursor\n */\ntype CursorState = {\n  /** Map of owner -> cursor */\n  cursorOwners: Map<string, CSSCursorType>;\n  /** Current active cursor (for priority tracking) */\n  currentCursor: CSSCursorType | null;\n  /** Current cursor owner (for priority tracking) */\n  currentOwner: string | null;\n};\n\n/**\n * Actions for cursor management\n */\ntype CursorActions = {\n  /** Request a cursor change */\n  requestCursorChange: (cursor: CSSCursorType, owner: string) => void;\n  /** Clear cursor for an owner */\n  clearCursor: (owner: string) => void;\n};\n\nconst cursorBus = Broadcast.getInstance<MapCursorEventType>();\nconst modeBus = Broadcast.getInstance<ModeChangedEvent>();\n\n/**\n * Lazy import to avoid circular dependency between cursor and mode stores.\n * The mode store doesn't depend on cursor store, but importing it synchronously\n * at module load time can cause initialization order issues.\n *\n * This pattern ensures the import is resolved before first use (bus listeners\n * are set up on first subscriber, not at module load time).\n */\nlet getModeOwnerFn: ((mapId: UniqueId) => string | undefined) | null = null;\nlet isRegisteredModeOwnerFn:\n  | ((mapId: UniqueId, owner: string) => boolean)\n  | null = null;\nlet importPromise: Promise<void> | null = null;\nlet importFailed = false;\n\nfunction ensureModeStoreImported(): void {\n  if (getModeOwnerFn !== null || importFailed) {\n    return;\n  }\n  if (importPromise === null) {\n    importPromise = import('../map-mode/store')\n      .then((mod) => {\n        getModeOwnerFn = mod.getCurrentModeOwner;\n        isRegisteredModeOwnerFn = mod.isRegisteredModeOwner;\n      })\n      .catch((error) => {\n        importFailed = true;\n        // Log error in development only - in production this is a silent fallback\n        if (process.env.NODE_ENV !== 'production') {\n          console.error('[MapCursor] Failed to import mode store:', error);\n        }\n      });\n  }\n}\n\n// Start the import immediately so it's likely resolved by first use\nensureModeStoreImported();\n\nfunction getModeOwner(mapId: UniqueId): string | undefined {\n  // getModeOwnerFn will be available by the time bus listeners are set up\n  // (which happens on first React subscriber, not at module load)\n  return getModeOwnerFn?.(mapId);\n}\n\nfunction isRegisteredOwner(mapId: UniqueId, owner: string): boolean {\n  return isRegisteredModeOwnerFn?.(mapId, owner) ?? false;\n}\n\n/**\n * Calculate effective cursor based on priority\n */\nfunction getEffectiveCursor(\n  mapId: UniqueId,\n  state: CursorState,\n): CSSCursorType {\n  // Priority 1: Mode owner's cursor\n  const modeOwner = getModeOwner?.(mapId);\n  if (modeOwner) {\n    const modeOwnerCursor = state.cursorOwners.get(modeOwner);\n    if (modeOwnerCursor) {\n      return modeOwnerCursor;\n    }\n  }\n\n  // Priority 2: Current cursor (if owner still has entry)\n  if (state.currentCursor && state.currentOwner) {\n    if (state.cursorOwners.has(state.currentOwner)) {\n      return state.currentCursor;\n    }\n  }\n\n  // Priority 3: Default\n  return DEFAULT_CURSOR;\n}\n\n/**\n * Cursor store\n */\nexport const cursorStore = createMapStore<CursorState, CursorActions>({\n  defaultState: {\n    cursorOwners: new Map(),\n    currentCursor: null,\n    currentOwner: null,\n  },\n\n  actions: (mapId, { get, set }) => ({\n    requestCursorChange: (cursor: CSSCursorType, owner: string) => {\n      const trimmedCursor = cursor.trim() as CSSCursorType;\n      const trimmedOwner = owner.trim();\n\n      if (!trimmedCursor) {\n        throw new Error('requestCursorChange requires non-empty cursor');\n      }\n      if (!trimmedOwner) {\n        throw new Error('requestCursorChange requires non-empty owner');\n      }\n\n      cursorBus.emit(MapCursorEvents.changeRequest, {\n        cursor: trimmedCursor,\n        owner: trimmedOwner,\n        id: mapId,\n      });\n    },\n\n    clearCursor: (owner: string) => {\n      const state = get();\n      const hadCursor = state.cursorOwners.has(owner);\n\n      if (hadCursor) {\n        // Clear current tracking if this was the owner\n        const updates: Partial<CursorState> = {\n          cursorOwners: mapDelete(state.cursorOwners, owner),\n        };\n        if (state.currentOwner === owner) {\n          updates.currentCursor = null;\n          updates.currentOwner = null;\n        }\n\n        set(updates);\n      }\n    },\n  }),\n\n  bus: (mapId, { get, set }) => {\n    // Handle cursor change requests\n    const unsubRequest = cursorBus.on(\n      MapCursorEvents.changeRequest,\n      (event) => {\n        const { cursor, owner: requestOwner, id } = event.payload;\n        if (id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const previousCursor = getEffectiveCursor(mapId, state);\n\n        // Skip if same cursor already stored for this owner\n        if (state.cursorOwners.get(requestOwner) === cursor) {\n          return;\n        }\n\n        // Create new Map for immutable update\n        const newCursorOwners = mapSet(\n          state.cursorOwners,\n          requestOwner,\n          cursor,\n        );\n\n        // Check ownership\n        const currentModeOwner = getModeOwner?.(mapId);\n        const isOwnerless = !currentModeOwner;\n        const isCurrentModeOwner = requestOwner === currentModeOwner;\n        const isAnyModeOwner = isRegisteredOwner(mapId, requestOwner);\n\n        if (isOwnerless || isCurrentModeOwner) {\n          // Accept: apply cursor with immutable update\n          const newState: CursorState = {\n            cursorOwners: newCursorOwners,\n            currentCursor: cursor,\n            currentOwner: requestOwner,\n          };\n\n          // Calculate new cursor with updated state\n          const newCursor = getEffectiveCursor(mapId, newState);\n\n          if (previousCursor !== newCursor) {\n            set(newState);\n            cursorBus.emit(MapCursorEvents.changed, {\n              previousCursor,\n              currentCursor: newCursor,\n              owner: requestOwner,\n              id: mapId,\n            });\n          } else {\n            // Still need to update state even if cursor didn't change visually\n            set(newState);\n          }\n        } else if (isAnyModeOwner) {\n          // Store but don't apply: requester owns a different mode (pending or not current).\n          // When their mode becomes active, getEffectiveCursor will find their cursor.\n          set({ cursorOwners: newCursorOwners });\n\n          cursorBus.emit(MapCursorEvents.rejected, {\n            rejectedCursor: cursor,\n            rejectedOwner: requestOwner,\n            currentOwner: state.currentOwner || currentModeOwner || 'unknown',\n            reason: 'not-current-owner',\n            id: mapId,\n          });\n        } else {\n          // Reject: don't store. Non-owners should only set cursor in default mode.\n          cursorBus.emit(MapCursorEvents.rejected, {\n            rejectedCursor: cursor,\n            rejectedOwner: requestOwner,\n            currentOwner: state.currentOwner || currentModeOwner || 'unknown',\n            reason: 'not-owner',\n            id: mapId,\n          });\n        }\n      },\n    );\n\n    // Handle mode changes\n    const unsubMode = modeBus.on(MapModeEvents.changed, (event) => {\n      if (event.payload.id !== mapId) {\n        return;\n      }\n\n      const state = get();\n      const previousCursor = getEffectiveCursor(mapId, state);\n\n      // Clear current tracking on mode change with immutable update\n      if (\n        event.payload.currentMode === 'default' ||\n        event.payload.previousMode !== event.payload.currentMode\n      ) {\n        set({\n          currentCursor: null,\n          currentOwner: null,\n        });\n      }\n\n      // Defer check until new mode owner is registered\n      queueMicrotask(() => {\n        // Re-get state after microtask since it may have changed\n        const currentState = get();\n        const newCursor = getEffectiveCursor(mapId, currentState);\n        if (previousCursor !== newCursor) {\n          const newModeOwner = getModeOwner?.(mapId) || 'system';\n          cursorBus.emit(MapCursorEvents.changed, {\n            previousCursor,\n            currentCursor: newCursor,\n            owner: newModeOwner,\n            id: mapId,\n          });\n        }\n      });\n    });\n\n    return () => {\n      unsubRequest();\n      unsubMode();\n    };\n  },\n});\n\n// =============================================================================\n// Convenience exports\n// =============================================================================\n\n/**\n * Get effective cursor (computed from state)\n */\nexport function getCursor(mapId: UniqueId): CSSCursorType {\n  return getEffectiveCursor(mapId, cursorStore.get(mapId));\n}\n\n/**\n * Hook for effective cursor value.\n *\n * **Internal use only** - not exported from the public API.\n * Use `useMapCursor` instead, which provides:\n * - MapContext integration (auto-resolves mapId inside MapProvider)\n * - Actions (requestCursorChange, clearCursor)\n * - Better ergonomics for consumers\n *\n * This hook exists for internal composition (used by useMapCursor).\n */\nexport function useCursor(mapId: UniqueId): CSSCursorType {\n  return cursorStore.useSelector(mapId, (state) =>\n    getEffectiveCursor(mapId, state),\n  );\n}\n\n/**\n * Clear cursor state\n */\nexport function clearCursorState(mapId: UniqueId): void {\n  cursorStore.clear(mapId);\n}\n"],"mappings":"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"}
+{"version":3,"file":"store.js","names":["DEFAULT_CURSOR: CSSCursorType","getModeOwnerFn: ((mapId: UniqueId) => string | undefined) | null","isRegisteredModeOwnerFn:\n  | ((mapId: UniqueId, owner: string) => boolean)\n  | null","importPromise: Promise<void> | null","updates: Partial<CursorState>","newState: CursorState"],"sources":["../../src/map-cursor/store.ts"],"sourcesContent":["/*\n * Copyright 2026 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Map Cursor Store\n *\n * Manages cursor state with ownership-based priority.\n *\n * Priority order:\n * 1. Mode owner's cursor (if mode is owned)\n * 2. Most recent cursor request\n * 3. Default cursor\n *\n * @example\n * ```tsx\n * import { cursorStore } from '@accelint/map-toolkit/map-cursor';\n *\n * function MapContainer({ mapId }) {\n *   const cursor = cursorStore.useSelector(mapId, (s) => getEffectiveCursor(mapId, s));\n *   return <div style={{ cursor }}>...</div>;\n * }\n *\n * // Request cursor change from a layer:\n * cursorStore.actions(mapId).requestCursorChange('crosshair', 'draw-layer');\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { MapModeEvents } from '../map-mode/events';\nimport { createMapStore, mapDelete, mapSet } from '../shared/create-map-store';\nimport { MapCursorEvents } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { ModeChangedEvent } from '../map-mode/types';\nimport type { CSSCursorType, MapCursorEventType } from './types';\n\nconst DEFAULT_CURSOR: CSSCursorType = 'default';\n\n/**\n * State shape for map cursor\n */\ntype CursorState = {\n  /** Map of owner -> cursor */\n  cursorOwners: Map<string, CSSCursorType>;\n  /** Current active cursor (for priority tracking) */\n  currentCursor: CSSCursorType | null;\n  /** Current cursor owner (for priority tracking) */\n  currentOwner: string | null;\n};\n\n/**\n * Actions for cursor management\n */\ntype CursorActions = {\n  /** Request a cursor change */\n  requestCursorChange: (cursor: CSSCursorType, owner: string) => void;\n  /** Clear cursor for an owner */\n  clearCursor: (owner: string) => void;\n};\n\nconst cursorBus = Broadcast.getInstance<MapCursorEventType>();\nconst modeBus = Broadcast.getInstance<ModeChangedEvent>();\n\n/**\n * Lazy import to avoid circular dependency between cursor and mode stores.\n * The mode store doesn't depend on cursor store, but importing it synchronously\n * at module load time can cause initialization order issues.\n *\n * This pattern ensures the import is resolved before first use (bus listeners\n * are set up on first subscriber, not at module load time).\n */\nlet getModeOwnerFn: ((mapId: UniqueId) => string | undefined) | null = null;\nlet isRegisteredModeOwnerFn:\n  | ((mapId: UniqueId, owner: string) => boolean)\n  | null = null;\nlet importPromise: Promise<void> | null = null;\nlet importFailed = false;\n\nfunction ensureModeStoreImported(): void {\n  if (getModeOwnerFn !== null || importFailed) {\n    return;\n  }\n  if (importPromise === null) {\n    importPromise = import('../map-mode/store')\n      .then((mod) => {\n        getModeOwnerFn = mod.getCurrentModeOwner;\n        isRegisteredModeOwnerFn = mod.isRegisteredModeOwner;\n      })\n      .catch((error) => {\n        importFailed = true;\n        // Log error in development only - in production this is a silent fallback\n        if (process.env.NODE_ENV !== 'production') {\n          console.error('[MapCursor] Failed to import mode store:', error);\n        }\n      });\n  }\n}\n\n// Start the import immediately so it's likely resolved by first use\nensureModeStoreImported();\n\nfunction getModeOwner(mapId: UniqueId): string | undefined {\n  // getModeOwnerFn will be available by the time bus listeners are set up\n  // (which happens on first React subscriber, not at module load)\n  return getModeOwnerFn?.(mapId);\n}\n\nfunction isRegisteredOwner(mapId: UniqueId, owner: string): boolean {\n  return isRegisteredModeOwnerFn?.(mapId, owner) ?? false;\n}\n\n/**\n * Calculate effective cursor based on priority.\n *\n * Priority order:\n * 1. Mode owner's cursor (if mode is owned)\n * 2. Most recent cursor request (if owner still has entry)\n * 3. Default cursor\n *\n * @param mapId - Unique identifier for the map instance\n * @param state - Current cursor state\n * @returns The effective cursor to display\n */\nfunction getEffectiveCursor(\n  mapId: UniqueId,\n  state: CursorState,\n): CSSCursorType {\n  // Priority 1: Mode owner's cursor\n  const modeOwner = getModeOwner?.(mapId);\n  if (modeOwner) {\n    const modeOwnerCursor = state.cursorOwners.get(modeOwner);\n    if (modeOwnerCursor) {\n      return modeOwnerCursor;\n    }\n  }\n\n  // Priority 2: Current cursor (if owner still has entry)\n  if (state.currentCursor && state.currentOwner) {\n    if (state.cursorOwners.has(state.currentOwner)) {\n      return state.currentCursor;\n    }\n  }\n\n  // Priority 3: Default\n  return DEFAULT_CURSOR;\n}\n\n/**\n * Cursor store\n */\nexport const cursorStore = createMapStore<CursorState, CursorActions>({\n  defaultState: {\n    cursorOwners: new Map(),\n    currentCursor: null,\n    currentOwner: null,\n  },\n\n  actions: (mapId, { get, set }) => ({\n    requestCursorChange: (cursor: CSSCursorType, owner: string) => {\n      const trimmedCursor = cursor.trim() as CSSCursorType;\n      const trimmedOwner = owner.trim();\n\n      if (!trimmedCursor) {\n        throw new Error('requestCursorChange requires non-empty cursor');\n      }\n      if (!trimmedOwner) {\n        throw new Error('requestCursorChange requires non-empty owner');\n      }\n\n      cursorBus.emit(MapCursorEvents.changeRequest, {\n        cursor: trimmedCursor,\n        owner: trimmedOwner,\n        id: mapId,\n      });\n    },\n\n    clearCursor: (owner: string) => {\n      const state = get();\n      const hadCursor = state.cursorOwners.has(owner);\n\n      if (hadCursor) {\n        // Clear current tracking if this was the owner\n        const updates: Partial<CursorState> = {\n          cursorOwners: mapDelete(state.cursorOwners, owner),\n        };\n        if (state.currentOwner === owner) {\n          updates.currentCursor = null;\n          updates.currentOwner = null;\n        }\n\n        set(updates);\n      }\n    },\n  }),\n\n  bus: (mapId, { get, set }) => {\n    // Handle cursor change requests\n    const unsubRequest = cursorBus.on(\n      MapCursorEvents.changeRequest,\n      (event) => {\n        const { cursor, owner: requestOwner, id } = event.payload;\n        if (id !== mapId) {\n          return;\n        }\n\n        const state = get();\n        const previousCursor = getEffectiveCursor(mapId, state);\n\n        // Skip if same cursor already stored for this owner\n        if (state.cursorOwners.get(requestOwner) === cursor) {\n          return;\n        }\n\n        // Create new Map for immutable update\n        const newCursorOwners = mapSet(\n          state.cursorOwners,\n          requestOwner,\n          cursor,\n        );\n\n        // Check ownership\n        const currentModeOwner = getModeOwner?.(mapId);\n        const isOwnerless = !currentModeOwner;\n        const isCurrentModeOwner = requestOwner === currentModeOwner;\n        const isAnyModeOwner = isRegisteredOwner(mapId, requestOwner);\n\n        if (isOwnerless || isCurrentModeOwner) {\n          // Accept: apply cursor with immutable update\n          const newState: CursorState = {\n            cursorOwners: newCursorOwners,\n            currentCursor: cursor,\n            currentOwner: requestOwner,\n          };\n\n          // Calculate new cursor with updated state\n          const newCursor = getEffectiveCursor(mapId, newState);\n\n          if (previousCursor !== newCursor) {\n            set(newState);\n            cursorBus.emit(MapCursorEvents.changed, {\n              previousCursor,\n              currentCursor: newCursor,\n              owner: requestOwner,\n              id: mapId,\n            });\n          } else {\n            // Still need to update state even if cursor didn't change visually\n            set(newState);\n          }\n        } else if (isAnyModeOwner) {\n          // Store but don't apply: requester owns a different mode (pending or not current).\n          // When their mode becomes active, getEffectiveCursor will find their cursor.\n          set({ cursorOwners: newCursorOwners });\n\n          cursorBus.emit(MapCursorEvents.rejected, {\n            rejectedCursor: cursor,\n            rejectedOwner: requestOwner,\n            currentOwner: state.currentOwner || currentModeOwner || 'unknown',\n            reason: 'not-current-owner',\n            id: mapId,\n          });\n        } else {\n          // Reject: don't store. Non-owners should only set cursor in default mode.\n          cursorBus.emit(MapCursorEvents.rejected, {\n            rejectedCursor: cursor,\n            rejectedOwner: requestOwner,\n            currentOwner: state.currentOwner || currentModeOwner || 'unknown',\n            reason: 'not-owner',\n            id: mapId,\n          });\n        }\n      },\n    );\n\n    // Handle mode changes\n    const unsubMode = modeBus.on(MapModeEvents.changed, (event) => {\n      if (event.payload.id !== mapId) {\n        return;\n      }\n\n      const state = get();\n      const previousCursor = getEffectiveCursor(mapId, state);\n\n      // Clear current tracking on mode change with immutable update\n      if (\n        event.payload.currentMode === 'default' ||\n        event.payload.previousMode !== event.payload.currentMode\n      ) {\n        set({\n          currentCursor: null,\n          currentOwner: null,\n        });\n      }\n\n      // Defer check until new mode owner is registered\n      queueMicrotask(() => {\n        // Re-get state after microtask since it may have changed\n        const currentState = get();\n        const newCursor = getEffectiveCursor(mapId, currentState);\n        if (previousCursor !== newCursor) {\n          const newModeOwner = getModeOwner?.(mapId) || 'system';\n          cursorBus.emit(MapCursorEvents.changed, {\n            previousCursor,\n            currentCursor: newCursor,\n            owner: newModeOwner,\n            id: mapId,\n          });\n        }\n      });\n    });\n\n    return () => {\n      unsubRequest();\n      unsubMode();\n    };\n  },\n});\n\n// =============================================================================\n// Convenience exports\n// =============================================================================\n\n/**\n * Get effective cursor value for a map instance.\n *\n * Computes the effective cursor from the current state by applying\n * the priority system (mode owner > most recent > default).\n *\n * @param mapId - Unique identifier for the map instance\n * @returns The effective cursor to display\n *\n * @example\n * ```typescript\n * import { getCursor } from '@accelint/map-toolkit/map-cursor';\n *\n * const currentCursor = getCursor(mapId);\n * console.log('Current cursor:', currentCursor); // 'default', 'pointer', etc.\n * ```\n */\nexport function getCursor(mapId: UniqueId): CSSCursorType {\n  return getEffectiveCursor(mapId, cursorStore.get(mapId));\n}\n\n/**\n * Hook for effective cursor value.\n *\n * **Internal use only** - not exported from the public API.\n * Use `useMapCursor` instead, which provides:\n * - MapContext integration (auto-resolves mapId inside MapProvider)\n * - Actions (requestCursorChange, clearCursor)\n * - Better ergonomics for consumers\n *\n * This hook exists for internal composition (used by useMapCursor).\n *\n * @param mapId - Unique identifier for the map instance\n * @returns The effective cursor to display\n */\nexport function useCursor(mapId: UniqueId): CSSCursorType {\n  return cursorStore.useSelector(mapId, (state) =>\n    getEffectiveCursor(mapId, state),\n  );\n}\n\n/**\n * Clear cursor state for a specific map instance.\n *\n * Removes all cursor ownership data and resets to default state.\n * This is typically not needed as cleanup happens automatically.\n * Use only in advanced scenarios where manual cleanup is required.\n *\n * @param mapId - Unique identifier for the map instance to clear\n * @returns void\n *\n * @example\n * ```typescript\n * import { clearCursorState } from '@accelint/map-toolkit/map-cursor';\n *\n * // Manual cleanup when destroying a map\n * clearCursorState(mapId);\n * ```\n */\nexport function clearCursorState(mapId: UniqueId): void {\n  cursorStore.clear(mapId);\n}\n"],"mappings":"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"}

package/dist/map-mode/store.d.ts

@@ -43,26 +43,65 @@ type MapModeActions = {
  */
 declare const modeStore: MapStore<MapModeState, MapModeActions>;
 /**
- * Get the current mode for a map instance
+ * Get the current mode for a map instance.
+ *
+ * @param mapId - Unique identifier for the map instance
+ * @returns The current active mode string
+ *
+ * @example
+ * ```typescript
+ * import { getMode } from '@accelint/map-toolkit/map-mode';
+ *
+ * const currentMode = getMode(mapId);
+ * console.log('Current mode:', currentMode); // 'default', 'drawing', etc.
+ * ```
  */
 declare function getMode(mapId: UniqueId): string;
 /**
- * Hook for current mode value
+ * Hook for current mode value.
+ *
+ * **Internal use only** - not exported from the public API.
+ * Use `useMapMode` instead for better ergonomics and MapContext integration.
+ *
+ * @param mapId - Unique identifier for the map instance
+ * @returns The current active mode string
  */
 declare function useMode(mapId: UniqueId): string;
 /**
- * Get the owner of the current mode for a given map instance
+ * Get the owner of the current mode for a given map instance.
+ *
  * @internal - For internal map-toolkit use only
+ * @param instanceId - Unique identifier for the map instance
+ * @returns The owner ID of the current mode, or undefined if unowned
  */
 declare function getCurrentModeOwner(instanceId: UniqueId): string | undefined;
 /**
  * Check if a given owner is registered as the owner of any mode.
  * This includes both active mode owners and pending mode requests.
+ *
  * @internal - For internal map-toolkit use only
+ * @param instanceId - Unique identifier for the map instance
+ * @param owner - The owner ID to check
+ * @returns True if the owner is registered for any mode
  */
 declare function isRegisteredModeOwner(instanceId: UniqueId, owner: string): boolean;
 /**
- * Manually clear map mode state for a specific instanceId.
+ * Manually clear map mode state for a specific map instance.
+ *
+ * Removes all mode ownership data, pending requests, and resets to default state.
+ * This is typically not needed as cleanup happens automatically.
+ * Use only in advanced scenarios where manual cleanup is required.
+ *
+ * @param instanceId - Unique identifier for the map instance to clear
+ * @returns void
+ *
+ * @example
+ * ```typescript
+ * import { clearMapModeState } from '@accelint/map-toolkit/map-mode';
+ *
+ * // Manual cleanup when destroying a map
+ * clearMapModeState(mapId);
+ * ```
  */
 declare function clearMapModeState(instanceId: UniqueId): void;
 //#endregion

package/dist/map-mode/store.js

@@ -14,8 +14,8 @@
 import { createMapStore, mapClear, mapDelete, mapSet } from "../shared/create-map-store.js";
 import { MapModeEvents } from "./events.js";
 import { Broadcast } from "@accelint/bus";
-import { uuid } from "@accelint/core";
 import { getLogger } from "@accelint/logger";
+import { uuid } from "@accelint/core";
 
 //#region src/map-mode/store.ts
 /**
@@ -53,7 +53,18 @@ const DEFAULT_MODE = "default";
 */
 const mapModeBus = Broadcast.getInstance();
 /**
-* Determine if a mode change request should be auto-accepted without authorization
+* Determine if a mode change request should be auto-accepted without authorization.
+*
+* Auto-accept conditions:
+* - Owner returning to default mode
+* - Owner switching between their own modes
+* - No ownership conflicts exist
+* - Entering an owned mode from default mode
+*
+* @param state - Current mode state
+* @param desiredMode - The mode being requested
+* @param requestOwner - The component requesting the mode change
+* @returns True if the request should be auto-accepted
 */
 function shouldAutoAcceptRequest(state, desiredMode, requestOwner) {
 	const currentModeOwner = state.modeOwners.get(state.mode);
@@ -222,20 +233,40 @@ const modeStore = createMapStore({
 	}
 });
 /**
-* Get the current mode for a map instance
+* Get the current mode for a map instance.
+*
+* @param mapId - Unique identifier for the map instance
+* @returns The current active mode string
+*
+* @example
+* ```typescript
+* import { getMode } from '@accelint/map-toolkit/map-mode';
+*
+* const currentMode = getMode(mapId);
+* console.log('Current mode:', currentMode); // 'default', 'drawing', etc.
+* ```
 */
 function getMode(mapId) {
 	return modeStore.get(mapId).mode;
 }
 /**
-* Hook for current mode value
+* Hook for current mode value.
+*
+* **Internal use only** - not exported from the public API.
+* Use `useMapMode` instead for better ergonomics and MapContext integration.
+*
+* @param mapId - Unique identifier for the map instance
+* @returns The current active mode string
 */
 function useMode(mapId) {
 	return modeStore.useSelector(mapId, (state) => state.mode);
 }
 /**
-* Get the owner of the current mode for a given map instance
+* Get the owner of the current mode for a given map instance.
+*
 * @internal - For internal map-toolkit use only
+* @param instanceId - Unique identifier for the map instance
+* @returns The owner ID of the current mode, or undefined if unowned
 */
 function getCurrentModeOwner(instanceId) {
 	const state = modeStore.get(instanceId);
@@ -244,7 +275,11 @@ function getCurrentModeOwner(instanceId) {
 /**
 * Check if a given owner is registered as the owner of any mode.
 * This includes both active mode owners and pending mode requests.
+*
 * @internal - For internal map-toolkit use only
+* @param instanceId - Unique identifier for the map instance
+* @param owner - The owner ID to check
+* @returns True if the owner is registered for any mode
 */
 function isRegisteredModeOwner(instanceId, owner) {
 	const state = modeStore.get(instanceId);
@@ -253,7 +288,22 @@ function isRegisteredModeOwner(instanceId, owner) {
 	return false;
 }
 /**
-* Manually clear map mode state for a specific instanceId.
+* Manually clear map mode state for a specific map instance.
+*
+* Removes all mode ownership data, pending requests, and resets to default state.
+* This is typically not needed as cleanup happens automatically.
+* Use only in advanced scenarios where manual cleanup is required.
+*
+* @param instanceId - Unique identifier for the map instance to clear
+* @returns void
+*
+* @example
+* ```typescript
+* import { clearMapModeState } from '@accelint/map-toolkit/map-mode';
+*
+* // Manual cleanup when destroying a map
+* clearMapModeState(mapId);
+* ```
 */
 function clearMapModeState(instanceId) {
 	modeStore.clear(instanceId);