@accelint/map-toolkit 0.5.0 → 1.0.0

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

@@ -1 +1 @@
-{"version":3,"file":"store.js","names":["DEFAULT_CURSOR: CSSCursorType"],"sources":["../../src/map-cursor/store.ts"],"sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { MapModeEvents } from '../map-mode/events';\nimport { getCurrentModeOwner } from '../map-mode/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\n/**\n * Default cursor value\n */\nconst DEFAULT_CURSOR: CSSCursorType = 'default';\n\n/**\n * Typed event bus instance for map cursor events.\n * Provides type-safe event emission and listening for all map cursor state changes.\n */\nconst mapCursorBus = Broadcast.getInstance<MapCursorEventType>();\n\n/**\n * Type representing the state for a single map cursor instance\n */\ntype MapCursorState = {\n  /** Map of owner-to-cursor mappings */\n  cursorOwners: Map<string, CSSCursorType>;\n  /** Current active cursor */\n  currentCursor: CSSCursorType | null;\n  /** Current cursor owner */\n  currentOwner: string | null;\n};\n\n/**\n * Store for map cursor state keyed by instanceId\n */\nconst cursorStore = new Map<UniqueId, MapCursorState>();\n\n/**\n * Track React component subscribers per instanceId (for fan-out notifications).\n * Each Set contains onStoreChange callbacks from useSyncExternalStore.\n */\nconst componentSubscribers = new Map<UniqueId, Set<() => void>>();\n\n/**\n * Cache of bus unsubscribe functions (1 per instanceId).\n * This ensures we only have one bus listener per map cursor instance, regardless of\n * how many React components subscribe to it.\n */\nconst busUnsubscribers = new Map<UniqueId, () => void>();\n\ntype Subscription = (onStoreChange: () => void) => () => void;\n/**\n * Cache of subscription functions per instanceId to avoid recreating on every render\n */\nconst subscriptionCache = new Map<UniqueId, Subscription>();\n\n/**\n * Cache of snapshot functions per instanceId to maintain referential stability\n */\nconst snapshotCache = new Map<UniqueId, () => CSSCursorType>();\n\n/**\n * Cache of server snapshot functions per instanceId to maintain referential stability.\n * Server snapshots always return default cursor since cursor state is client-only.\n */\nconst serverSnapshotCache = new Map<UniqueId, () => CSSCursorType>();\n\n/**\n * Cache of requestCursorChange functions per instanceId to maintain referential stability\n */\nconst requestCursorChangeCache = new Map<\n  UniqueId,\n  (cursor: CSSCursorType, owner: string) => void\n>();\n\n/**\n * Cache of clearCursor functions per instanceId to maintain referential stability\n */\nconst clearCursorCache = new Map<UniqueId, (owner: string) => void>();\n\n/**\n * All state caches that need cleanup when an instance is removed\n */\nconst stateCaches = [\n  cursorStore,\n  componentSubscribers,\n  subscriptionCache,\n  snapshotCache,\n  serverSnapshotCache,\n  requestCursorChangeCache,\n  clearCursorCache,\n] as const;\n\n/**\n * Clear all cached state for a given instanceId\n */\nfunction clearAllCaches(instanceId: UniqueId): void {\n  stateCaches.map((cache) => cache.delete(instanceId));\n}\n\n/**\n * Get or create cursor state for a given instanceId\n */\nfunction getOrCreateState(instanceId: UniqueId): MapCursorState {\n  if (!cursorStore.has(instanceId)) {\n    cursorStore.set(instanceId, {\n      cursorOwners: new Map(),\n      currentCursor: null,\n      currentOwner: null,\n    });\n  }\n  // biome-ignore lint/style/noNonNullAssertion: State guaranteed to exist after has() check above\n  return cursorStore.get(instanceId)!;\n}\n\n/**\n * Get current cursor snapshot for a given instance (for useSyncExternalStore)\n *\n * Priority order:\n * 1. Mode owner's cursor (if exists and mode is owned)\n * 2. Most recent cursor (only if currentOwner still has an entry in storage)\n * 3. Default cursor\n */\nfunction getSnapshot(instanceId: UniqueId): CSSCursorType {\n  const state = cursorStore.get(instanceId);\n  if (!state) {\n    return DEFAULT_CURSOR;\n  }\n\n  // Priority 1: Mode owner's cursor\n  const modeOwner = getCurrentModeOwner(instanceId);\n  if (modeOwner) {\n    const modeOwnerCursor = state.cursorOwners.get(modeOwner);\n    if (modeOwnerCursor) {\n      return modeOwnerCursor;\n    }\n  }\n\n  // Priority 2: Most recent cursor (only if owner entry still exists)\n  if (state.currentCursor && state.currentOwner) {\n    if (state.cursorOwners.has(state.currentOwner)) {\n      return state.currentCursor;\n    }\n  }\n\n  // Priority 3: Default cursor\n  return DEFAULT_CURSOR;\n}\n\n/**\n * Notify all React subscribers for a given instanceId\n */\nfunction notifySubscribers(instanceId: UniqueId): void {\n  const subscribers = componentSubscribers.get(instanceId);\n  if (subscribers) {\n    for (const onStoreChange of subscribers) {\n      onStoreChange();\n    }\n  }\n}\n\n/**\n * Handle cursor change request for a given instance\n */\nfunction handleCursorChangeRequest(\n  instanceId: UniqueId,\n  state: MapCursorState,\n  cursor: CSSCursorType,\n  requestOwner: string,\n): void {\n  const previousCursor = getSnapshot(instanceId);\n\n  // Skip if same cursor is already stored for this owner\n  if (state.cursorOwners.get(requestOwner) === cursor) {\n    return;\n  }\n\n  // Store cursor for this owner\n  state.cursorOwners.set(requestOwner, cursor);\n\n  // Check if requester is the mode owner or if mode is ownerless\n  const modeOwner = getCurrentModeOwner(instanceId);\n  const isOwnerlessMode = !modeOwner;\n  const isRequestOwnerModeOwner = requestOwner === modeOwner;\n\n  // Grant or reject based on ownership\n  if (isOwnerlessMode || isRequestOwnerModeOwner) {\n    // Accept: store and apply cursor\n    state.currentCursor = cursor;\n    state.currentOwner = requestOwner;\n\n    const newCursor = getSnapshot(instanceId);\n\n    // Emit changed event only if cursor actually changed\n    if (previousCursor !== newCursor) {\n      mapCursorBus.emit(MapCursorEvents.changed, {\n        previousCursor,\n        currentCursor: newCursor,\n        owner: requestOwner,\n        id: instanceId,\n      });\n      notifySubscribers(instanceId);\n    }\n  } else {\n    // Reject: stored for future auto-apply, but emit rejection event\n    mapCursorBus.emit(MapCursorEvents.rejected, {\n      rejectedCursor: cursor,\n      rejectedOwner: requestOwner,\n      currentOwner: state.currentOwner || modeOwner || 'unknown',\n      reason: 'not-owner',\n      id: instanceId,\n    });\n  }\n}\n\n/**\n * Ensures a single bus listener exists for the given instanceId.\n * All React subscribers will be notified via fan-out when the bus events fire.\n * This prevents creating N bus listeners for N React components.\n *\n * @param instanceId - The unique identifier for the map cursor instance\n */\nfunction ensureBusListener(instanceId: UniqueId): void {\n  if (busUnsubscribers.has(instanceId)) {\n    return; // Already listening\n  }\n\n  const state = getOrCreateState(instanceId);\n\n  // Listen for cursor change requests\n  const unsubRequest = mapCursorBus.on(\n    MapCursorEvents.changeRequest,\n    (event) => {\n      const { cursor, owner: requestOwner, id } = event.payload;\n      if (id !== instanceId) {\n        return;\n      }\n      handleCursorChangeRequest(instanceId, state, cursor, requestOwner);\n    },\n  );\n\n  // Listen for mode changes\n  const modeBus = Broadcast.getInstance<ModeChangedEvent>();\n  const unsubModeChange = modeBus.on(MapModeEvents.changed, (event) => {\n    if (event.payload.id !== instanceId) {\n      return;\n    }\n\n    const previousCursor = getSnapshot(instanceId);\n\n    // When mode changes, clear current cursor tracking (but keep owner's cursor in storage)\n    // This allows the cursor to fall back to state-based default until a new owner sets it\n    if (\n      event.payload.currentMode === 'default' ||\n      event.payload.previousMode !== event.payload.currentMode\n    ) {\n      state.currentCursor = null;\n      state.currentOwner = null;\n      notifySubscribers(instanceId);\n    }\n\n    // Defer cursor change check until after new mode owner is registered\n    queueMicrotask(() => {\n      const newCursor = getSnapshot(instanceId);\n      if (previousCursor !== newCursor) {\n        const newModeOwner = getCurrentModeOwner(instanceId) || 'system';\n        mapCursorBus.emit(MapCursorEvents.changed, {\n          previousCursor,\n          currentCursor: newCursor,\n          owner: newModeOwner,\n          id: instanceId,\n        });\n        notifySubscribers(instanceId);\n      }\n    });\n  });\n\n  // Store composite cleanup function\n  busUnsubscribers.set(instanceId, () => {\n    unsubRequest();\n    unsubModeChange();\n  });\n}\n\n/**\n * Cleans up the bus listener if no React subscribers remain.\n *\n * @param instanceId - The unique identifier for the map cursor instance\n */\nfunction cleanupBusListenerIfNeeded(instanceId: UniqueId): void {\n  const subscribers = componentSubscribers.get(instanceId);\n\n  if (!subscribers || subscribers.size === 0) {\n    // No more React subscribers - clean up bus listener\n    const unsub = busUnsubscribers.get(instanceId);\n    if (unsub) {\n      unsub();\n      busUnsubscribers.delete(instanceId);\n    }\n\n    // Clean up all state\n    clearAllCaches(instanceId);\n  }\n}\n\n/**\n * Creates or retrieves a cached subscription function for a given instanceId.\n * Uses a fan-out pattern: 1 bus listener -> N React subscribers.\n * Automatically cleans up cursor state when the last subscriber unsubscribes.\n *\n * @param instanceId - The unique identifier for the map cursor instance\n * @returns A subscription function for useSyncExternalStore\n */\nexport function getOrCreateSubscription(\n  instanceId: UniqueId,\n): (onStoreChange: () => void) => () => void {\n  const subscription =\n    subscriptionCache.get(instanceId) ??\n    ((onStoreChange: () => void) => {\n      // Ensure state exists\n      getOrCreateState(instanceId);\n\n      // Ensure single bus listener exists for this instanceId\n      ensureBusListener(instanceId);\n\n      // Get or create the subscriber set for this map instance, then add this component's callback\n      let subscriberSet = componentSubscribers.get(instanceId);\n      if (!subscriberSet) {\n        subscriberSet = new Set();\n        componentSubscribers.set(instanceId, subscriberSet);\n      }\n      subscriberSet.add(onStoreChange);\n\n      // Return cleanup function to remove this component's subscription\n      return () => {\n        const currentSubscriberSet = componentSubscribers.get(instanceId);\n        if (currentSubscriberSet) {\n          currentSubscriberSet.delete(onStoreChange);\n        }\n\n        // Clean up bus listener if this was the last React subscriber\n        cleanupBusListenerIfNeeded(instanceId);\n      };\n    });\n\n  subscriptionCache.set(instanceId, subscription);\n\n  return subscription;\n}\n\n/**\n * Creates or retrieves a cached snapshot function for a given instanceId.\n * The cursor returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.\n *\n * @param instanceId - The unique identifier for the map cursor instance\n * @returns A snapshot function for useSyncExternalStore\n */\nexport function getOrCreateSnapshot(instanceId: UniqueId): () => CSSCursorType {\n  const snapshot =\n    snapshotCache.get(instanceId) ?? (() => getSnapshot(instanceId));\n\n  snapshotCache.set(instanceId, snapshot);\n\n  return snapshot;\n}\n\n/**\n * Creates or retrieves a cached server snapshot function for a given instanceId.\n * Server snapshots always return the default cursor since cursor state is client-only.\n * Required for SSR/RSC compatibility with useSyncExternalStore.\n *\n * @param instanceId - The unique identifier for the map cursor instance\n * @returns A server snapshot function for useSyncExternalStore\n */\nexport function getOrCreateServerSnapshot(\n  instanceId: UniqueId,\n): () => CSSCursorType {\n  const serverSnapshot =\n    serverSnapshotCache.get(instanceId) ?? (() => DEFAULT_CURSOR);\n\n  serverSnapshotCache.set(instanceId, serverSnapshot);\n\n  return serverSnapshot;\n}\n\n/**\n * Creates or retrieves a cached requestCursorChange function for a given instanceId.\n * This maintains referential stability for the function reference.\n *\n * @param instanceId - The unique identifier for the map cursor instance\n * @returns A requestCursorChange function for this instance\n */\nexport function getOrCreateRequestCursorChange(\n  instanceId: UniqueId,\n): (cursor: CSSCursorType, owner: string) => void {\n  const requestCursorChange =\n    requestCursorChangeCache.get(instanceId) ??\n    ((cursor: CSSCursorType, owner: string) => {\n      const trimmedCursor = cursor.trim();\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      mapCursorBus.emit(MapCursorEvents.changeRequest, {\n        cursor: trimmedCursor as CSSCursorType,\n        owner: trimmedOwner,\n        id: instanceId,\n      });\n    });\n\n  requestCursorChangeCache.set(instanceId, requestCursorChange);\n\n  return requestCursorChange;\n}\n\n/**\n * Creates or retrieves a cached clearCursor function for a given instanceId.\n * This maintains referential stability for the function reference.\n *\n * @param instanceId - The unique identifier for the map cursor instance\n * @returns A clearCursor function for this instance\n */\nexport function getOrCreateClearCursor(\n  instanceId: UniqueId,\n): (owner: string) => void {\n  const clearCursor =\n    clearCursorCache.get(instanceId) ??\n    ((owner: string) => {\n      const state = cursorStore.get(instanceId);\n      if (!state) {\n        return;\n      }\n\n      const hadCursor = state.cursorOwners.has(owner);\n      state.cursorOwners.delete(owner);\n\n      // If this was the current owner, clear current tracking\n      if (state.currentOwner === owner) {\n        state.currentCursor = null;\n        state.currentOwner = null;\n      }\n\n      // Only notify if cursor changed\n      if (hadCursor) {\n        notifySubscribers(instanceId);\n      }\n    });\n\n  clearCursorCache.set(instanceId, clearCursor);\n\n  return clearCursor;\n}\n\n/**\n * Get the current cursor for a given instance (direct access, not reactive).\n * @internal - For internal map-toolkit use only\n *\n * @param instanceId - The unique identifier for the map instance\n * @returns The current cursor\n */\nexport function getCursor(instanceId: UniqueId): CSSCursorType {\n  return getSnapshot(instanceId);\n}\n\n/**\n * Manually clear all cursor state for a specific instanceId.\n * This is typically not needed as cleanup happens automatically when all subscribers unmount.\n * Use this only in advanced scenarios where manual cleanup is required.\n *\n * @param instanceId - The unique identifier for the map cursor instance to clear\n *\n * @example\n * ```tsx\n * // Manual cleanup (rarely needed)\n * clearCursorState('my-map-instance');\n * ```\n */\nexport function clearCursorState(instanceId: UniqueId): void {\n  // Unsubscribe from bus if listening\n  const unsub = busUnsubscribers.get(instanceId);\n  if (unsub) {\n    unsub();\n    busUnsubscribers.delete(instanceId);\n  }\n\n  // Clear all state\n  clearAllCaches(instanceId);\n}\n\n// Legacy API compatibility (for tests and existing code)\n/** @deprecated Use module functions directly */\nexport function getOrCreateStore(id: UniqueId): {\n  getSnapshot: () => CSSCursorType;\n} {\n  return {\n    getSnapshot: () => getSnapshot(id),\n  };\n}\n\n/** @deprecated Use clearCursorState instead */\nexport function destroyStore(id: UniqueId): void {\n  clearCursorState(id);\n}\n\n/** @deprecated Use direct function calls instead */\nexport function getStore(\n  id: UniqueId,\n): { getSnapshot: () => CSSCursorType } | undefined {\n  // Always return a store object since we don't track \"existence\" anymore\n  return {\n    getSnapshot: () => getSnapshot(id),\n  };\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 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/**\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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"}

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

@@ -80,7 +80,10 @@ declare function useMapCursor(id?: UniqueId): UseMapCursorReturn;
  * This hook automatically requests a cursor when mounted and clears it when unmounted.
  * Useful for components that need to consistently show a specific cursor.
  *
- * @param cursor - The cursor to request
+ * NOTE: This hook does NOT re-render when cursor state changes. If you need to read
+ * the current cursor value, use `useMapCursor` instead.
+ *
+ * @param cursorType - The cursor to request
  * @param owner - The owner identifier
  * @param id - Optional map instance ID
  *
@@ -93,7 +96,7 @@ declare function useMapCursor(id?: UniqueId): UseMapCursorReturn;
  * }
  * ```
  */
-declare function useMapCursorEffect(cursor: CSSCursorType, owner: string, id?: UniqueId): void;
+declare function useMapCursorEffect(cursorType: CSSCursorType, owner: string, id?: UniqueId): void;
 //#endregion
 export { UseMapCursorReturn, useMapCursor, useMapCursorEffect };
 //# sourceMappingURL=use-map-cursor.d.ts.map

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

@@ -13,9 +13,9 @@
 
 'use client';
 
-import { getOrCreateClearCursor, getOrCreateRequestCursorChange, getOrCreateServerSnapshot, getOrCreateSnapshot, getOrCreateSubscription } from "./store.js";
+import { cursorStore, useCursor } from "./store.js";
 import { MapContext } from "../deckgl/base-map/provider.js";
-import { useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+import { useContext, useEffect, useMemo, useRef } from "react";
 
 //#region src/map-cursor/use-map-cursor.ts
 /**
@@ -70,12 +70,13 @@ function useMapCursor(id) {
 	const contextId = useContext(MapContext);
 	const actualId = id ?? contextId;
 	if (!actualId) throw new Error("useMapCursor requires either an id parameter or to be used within a MapProvider");
-	const cursor = useSyncExternalStore(getOrCreateSubscription(actualId), getOrCreateSnapshot(actualId), getOrCreateServerSnapshot(actualId));
+	const cursor = useCursor(actualId);
+	const actions = useMemo(() => cursorStore.actions(actualId), [actualId]);
 	return useMemo(() => ({
 		cursor,
-		requestCursorChange: getOrCreateRequestCursorChange(actualId),
-		clearCursor: getOrCreateClearCursor(actualId)
-	}), [cursor, actualId]);
+		requestCursorChange: actions.requestCursorChange,
+		clearCursor: actions.clearCursor
+	}), [cursor, actions]);
 }
 /**
 * Hook to automatically manage cursor for a component's lifecycle.
@@ -83,7 +84,10 @@ function useMapCursor(id) {
 * This hook automatically requests a cursor when mounted and clears it when unmounted.
 * Useful for components that need to consistently show a specific cursor.
 *
-* @param cursor - The cursor to request
+* NOTE: This hook does NOT re-render when cursor state changes. If you need to read
+* the current cursor value, use `useMapCursor` instead.
+*
+* @param cursorType - The cursor to request
 * @param owner - The owner identifier
 * @param id - Optional map instance ID
 *
@@ -96,18 +100,32 @@ function useMapCursor(id) {
 * }
 * ```
 */
-function useMapCursorEffect(cursor, owner, id) {
-	const { requestCursorChange, clearCursor } = useMapCursor(id);
+function useMapCursorEffect(cursorType, owner, id) {
+	const contextId = useContext(MapContext);
+	const actualId = id ?? contextId;
+	if (!actualId) throw new Error("useMapCursorEffect requires either an id parameter or to be used within a MapProvider");
+	const cursorRef = useRef(cursorType);
+	const ownerRef = useRef(owner);
+	const idRef = useRef(actualId);
+	cursorRef.current = cursorType;
+	ownerRef.current = owner;
+	idRef.current = actualId;
 	useEffect(() => {
-		requestCursorChange(cursor, owner);
+		const mapId = idRef.current;
+		const unsubscribe = cursorStore.subscribe(mapId)(() => {});
 		return () => {
-			clearCursor(owner);
+			unsubscribe();
+			queueMicrotask(() => {
+				cursorStore.actions(idRef.current).clearCursor(ownerRef.current);
+			});
 		};
+	}, []);
+	useEffect(() => {
+		cursorStore.actions(actualId).requestCursorChange(cursorType, owner);
 	}, [
-		cursor,
-		owner,
-		requestCursorChange,
-		clearCursor
+		actualId,
+		cursorType,
+		owner
 	]);
 }
 

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

@@ -1 +1 @@
-{"version":3,"file":"use-map-cursor.js","names":[],"sources":["../../src/map-cursor/use-map-cursor.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'use client';\n\nimport 'client-only';\nimport { useContext, useEffect, useMemo, useSyncExternalStore } from 'react';\nimport { MapContext } from '../deckgl/base-map/provider';\nimport {\n  getOrCreateClearCursor,\n  getOrCreateRequestCursorChange,\n  getOrCreateServerSnapshot,\n  getOrCreateSnapshot,\n  getOrCreateSubscription,\n} from './store';\nimport type { UniqueId } from '@accelint/core';\nimport type { CSSCursorType } from './types';\n\n/**\n * Return value for the useMapCursor hook\n */\nexport type UseMapCursorReturn = {\n  /** The current active cursor */\n  cursor: CSSCursorType;\n  /** Function to request a cursor change with ownership */\n  requestCursorChange: (cursor: CSSCursorType, requestOwner: string) => void;\n  /** Function to clear cursor for an owner */\n  clearCursor: (owner: string) => void;\n};\n\n/**\n * Hook to access the map cursor state and actions.\n *\n * This hook uses `useSyncExternalStore` to subscribe to map cursor state changes,\n * providing concurrent-safe cursor state updates. Uses a fan-out pattern where\n * a single bus listener per map instance notifies N React component subscribers.\n *\n * **Owner-based Priority System:**\n * - Mode owners (from MapModeStore) have highest priority\n * - Non-owners can set cursors only in default/ownerless modes\n * - Rejected requests emit events with rejection reasons\n *\n * @param id - Optional map instance ID. If not provided, will use the ID from `MapContext`.\n * @returns The current cursor, requestCursorChange function, and clearCursor function\n * @throws Error if no `id` is provided and hook is used outside of `MapProvider`\n *\n * @example\n * ```tsx\n * // Inside MapProvider (within BaseMap children)\n * function CustomDeckLayer() {\n *   const { cursor, requestCursorChange, clearCursor } = useMapCursor();\n *\n *   const handleHover = (info: PickingInfo) => {\n *     if (info.object) {\n *       requestCursorChange('pointer', 'custom-layer-id');\n *     } else {\n *       clearCursor('custom-layer-id');\n *     }\n *   };\n *\n *   return <ScatterplotLayer onHover={handleHover} />;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Outside MapProvider - pass id directly\n * function ExternalControl({ mapId }: { mapId: UniqueId }) {\n *   const { cursor, requestCursorChange } = useMapCursor(mapId);\n *\n *   return (\n *     <button onClick={() => requestCursorChange('crosshair', 'external-control')}>\n *       Set Crosshair (current: {cursor})\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useMapCursor(id?: UniqueId): UseMapCursorReturn {\n  const contextId = useContext(MapContext);\n  const actualId = id ?? contextId;\n\n  if (!actualId) {\n    throw new Error(\n      'useMapCursor requires either an id parameter or to be used within a MapProvider',\n    );\n  }\n\n  // Subscribe to store using useSyncExternalStore with fan-out pattern\n  // Third parameter provides server snapshot for SSR/RSC compatibility\n  const cursor = useSyncExternalStore(\n    getOrCreateSubscription(actualId),\n    getOrCreateSnapshot(actualId),\n    getOrCreateServerSnapshot(actualId),\n  );\n\n  // Memoize the return value to prevent unnecessary re-renders\n  return useMemo(\n    () => ({\n      cursor,\n      requestCursorChange: getOrCreateRequestCursorChange(actualId),\n      clearCursor: getOrCreateClearCursor(actualId),\n    }),\n    [cursor, actualId],\n  );\n}\n\n/**\n * Hook to automatically manage cursor for a component's lifecycle.\n *\n * This hook automatically requests a cursor when mounted and clears it when unmounted.\n * Useful for components that need to consistently show a specific cursor.\n *\n * @param cursor - The cursor to request\n * @param owner - The owner identifier\n * @param id - Optional map instance ID\n *\n * @example\n * ```tsx\n * function DrawingMode() {\n *   useMapCursorEffect('crosshair', 'drawing-mode');\n *\n *   return <div>Drawing mode active with crosshair cursor</div>;\n * }\n * ```\n */\nexport function useMapCursorEffect(\n  cursor: CSSCursorType,\n  owner: string,\n  id?: UniqueId,\n): void {\n  const { requestCursorChange, clearCursor } = useMapCursor(id);\n\n  useEffect(() => {\n    requestCursorChange(cursor, owner);\n\n    return () => {\n      clearCursor(owner);\n    };\n  }, [cursor, owner, requestCursorChange, clearCursor]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsFA,SAAgB,aAAa,IAAmC;CAC9D,MAAM,YAAY,WAAW,WAAW;CACxC,MAAM,WAAW,MAAM;AAEvB,KAAI,CAAC,SACH,OAAM,IAAI,MACR,kFACD;CAKH,MAAM,SAAS,qBACb,wBAAwB,SAAS,EACjC,oBAAoB,SAAS,EAC7B,0BAA0B,SAAS,CACpC;AAGD,QAAO,eACE;EACL;EACA,qBAAqB,+BAA+B,SAAS;EAC7D,aAAa,uBAAuB,SAAS;EAC9C,GACD,CAAC,QAAQ,SAAS,CACnB;;;;;;;;;;;;;;;;;;;;;AAsBH,SAAgB,mBACd,QACA,OACA,IACM;CACN,MAAM,EAAE,qBAAqB,gBAAgB,aAAa,GAAG;AAE7D,iBAAgB;AACd,sBAAoB,QAAQ,MAAM;AAElC,eAAa;AACX,eAAY,MAAM;;IAEnB;EAAC;EAAQ;EAAO;EAAqB;EAAY,CAAC"}
+{"version":3,"file":"use-map-cursor.js","names":[],"sources":["../../src/map-cursor/use-map-cursor.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'use client';\n\nimport 'client-only';\nimport { useContext, useEffect, useMemo, useRef } from 'react';\nimport { MapContext } from '../deckgl/base-map/provider';\nimport { cursorStore, useCursor } from './store';\nimport type { UniqueId } from '@accelint/core';\nimport type { CSSCursorType } from './types';\n\n/**\n * Return value for the useMapCursor hook\n */\nexport type UseMapCursorReturn = {\n  /** The current active cursor */\n  cursor: CSSCursorType;\n  /** Function to request a cursor change with ownership */\n  requestCursorChange: (cursor: CSSCursorType, requestOwner: string) => void;\n  /** Function to clear cursor for an owner */\n  clearCursor: (owner: string) => void;\n};\n\n/**\n * Hook to access the map cursor state and actions.\n *\n * This hook uses `useSyncExternalStore` to subscribe to map cursor state changes,\n * providing concurrent-safe cursor state updates. Uses a fan-out pattern where\n * a single bus listener per map instance notifies N React component subscribers.\n *\n * **Owner-based Priority System:**\n * - Mode owners (from MapModeStore) have highest priority\n * - Non-owners can set cursors only in default/ownerless modes\n * - Rejected requests emit events with rejection reasons\n *\n * @param id - Optional map instance ID. If not provided, will use the ID from `MapContext`.\n * @returns The current cursor, requestCursorChange function, and clearCursor function\n * @throws Error if no `id` is provided and hook is used outside of `MapProvider`\n *\n * @example\n * ```tsx\n * // Inside MapProvider (within BaseMap children)\n * function CustomDeckLayer() {\n *   const { cursor, requestCursorChange, clearCursor } = useMapCursor();\n *\n *   const handleHover = (info: PickingInfo) => {\n *     if (info.object) {\n *       requestCursorChange('pointer', 'custom-layer-id');\n *     } else {\n *       clearCursor('custom-layer-id');\n *     }\n *   };\n *\n *   return <ScatterplotLayer onHover={handleHover} />;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Outside MapProvider - pass id directly\n * function ExternalControl({ mapId }: { mapId: UniqueId }) {\n *   const { cursor, requestCursorChange } = useMapCursor(mapId);\n *\n *   return (\n *     <button onClick={() => requestCursorChange('crosshair', 'external-control')}>\n *       Set Crosshair (current: {cursor})\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useMapCursor(id?: UniqueId): UseMapCursorReturn {\n  const contextId = useContext(MapContext);\n  const actualId = id ?? contextId;\n\n  if (!actualId) {\n    throw new Error(\n      'useMapCursor requires either an id parameter or to be used within a MapProvider',\n    );\n  }\n\n  // Use the useCursor hook which computes effective cursor with priority\n  const cursor = useCursor(actualId);\n\n  // Get actions from the store - cursorStore.actions returns stable references\n  // (cached per mapId), so we can memoize on actualId only\n  const actions = useMemo(() => cursorStore.actions(actualId), [actualId]);\n\n  // Memoize the return value to prevent unnecessary re-renders\n  return useMemo(\n    () => ({\n      cursor,\n      requestCursorChange: actions.requestCursorChange,\n      clearCursor: actions.clearCursor,\n    }),\n    [cursor, actions],\n  );\n}\n\n/**\n * Hook to automatically manage cursor for a component's lifecycle.\n *\n * This hook automatically requests a cursor when mounted and clears it when unmounted.\n * Useful for components that need to consistently show a specific cursor.\n *\n * NOTE: This hook does NOT re-render when cursor state changes. If you need to read\n * the current cursor value, use `useMapCursor` instead.\n *\n * @param cursorType - The cursor to request\n * @param owner - The owner identifier\n * @param id - Optional map instance ID\n *\n * @example\n * ```tsx\n * function DrawingMode() {\n *   useMapCursorEffect('crosshair', 'drawing-mode');\n *\n *   return <div>Drawing mode active with crosshair cursor</div>;\n * }\n * ```\n */\nexport function useMapCursorEffect(\n  cursorType: CSSCursorType,\n  owner: string,\n  id?: UniqueId,\n): void {\n  const contextId = useContext(MapContext);\n  const actualId = id ?? contextId;\n\n  if (!actualId) {\n    throw new Error(\n      'useMapCursorEffect requires either an id parameter or to be used within a MapProvider',\n    );\n  }\n\n  // Store values in refs for stable cleanup function access\n  const cursorRef = useRef(cursorType);\n  const ownerRef = useRef(owner);\n  const idRef = useRef(actualId);\n\n  // Update refs on each render\n  cursorRef.current = cursorType;\n  ownerRef.current = owner;\n  idRef.current = actualId;\n\n  // Subscribe to store (to ensure bus listeners are set up) on mount only\n  useEffect(() => {\n    const mapId = idRef.current;\n\n    // Subscribe to store to ensure bus listeners are set up\n    // The subscription callback is a no-op since we don't want to re-render\n    const unsubscribe = cursorStore.subscribe(mapId)(() => {\n      // No-op: we don't want cursor state changes to trigger re-renders\n    });\n\n    return () => {\n      // Unsubscribe first to prevent re-render loops\n      unsubscribe();\n\n      // IMPORTANT: Defer cursor clear using queueMicrotask to avoid the React error:\n      // \"Cannot update a component while rendering a different component\"\n      //\n      // Effect cleanup runs during React's commit phase. If clearCursor() triggers\n      // a state update synchronously (via store.set() -> notify subscribers), it can\n      // cause React to attempt re-rendering while still committing the current tree.\n      //\n      // queueMicrotask schedules the cleanup to run after the current commit phase\n      // completes, allowing React to finish its work before the state update occurs.\n      queueMicrotask(() => {\n        const cleanupActions = cursorStore.actions(idRef.current);\n        cleanupActions.clearCursor(ownerRef.current);\n      });\n    };\n  }, []);\n\n  // Request cursor when cursorType or owner changes\n  useEffect(() => {\n    const actions = cursorStore.actions(actualId);\n    actions.requestCursorChange(cursorType, owner);\n  }, [actualId, cursorType, owner]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgFA,SAAgB,aAAa,IAAmC;CAC9D,MAAM,YAAY,WAAW,WAAW;CACxC,MAAM,WAAW,MAAM;AAEvB,KAAI,CAAC,SACH,OAAM,IAAI,MACR,kFACD;CAIH,MAAM,SAAS,UAAU,SAAS;CAIlC,MAAM,UAAU,cAAc,YAAY,QAAQ,SAAS,EAAE,CAAC,SAAS,CAAC;AAGxE,QAAO,eACE;EACL;EACA,qBAAqB,QAAQ;EAC7B,aAAa,QAAQ;EACtB,GACD,CAAC,QAAQ,QAAQ,CAClB;;;;;;;;;;;;;;;;;;;;;;;;AAyBH,SAAgB,mBACd,YACA,OACA,IACM;CACN,MAAM,YAAY,WAAW,WAAW;CACxC,MAAM,WAAW,MAAM;AAEvB,KAAI,CAAC,SACH,OAAM,IAAI,MACR,wFACD;CAIH,MAAM,YAAY,OAAO,WAAW;CACpC,MAAM,WAAW,OAAO,MAAM;CAC9B,MAAM,QAAQ,OAAO,SAAS;AAG9B,WAAU,UAAU;AACpB,UAAS,UAAU;AACnB,OAAM,UAAU;AAGhB,iBAAgB;EACd,MAAM,QAAQ,MAAM;EAIpB,MAAM,cAAc,YAAY,UAAU,MAAM,OAAO,GAErD;AAEF,eAAa;AAEX,gBAAa;AAWb,wBAAqB;AAEnB,IADuB,YAAY,QAAQ,MAAM,QAAQ,CAC1C,YAAY,SAAS,QAAQ;KAC5C;;IAEH,EAAE,CAAC;AAGN,iBAAgB;AAEd,EADgB,YAAY,QAAQ,SAAS,CACrC,oBAAoB,YAAY,MAAM;IAC7C;EAAC;EAAU;EAAY;EAAM,CAAC"}

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

@@ -11,7 +11,7 @@
  */
 
 import { MapModeEvents, MapModeEventsNamespace } from "./events.js";
-import { clearMapModeState, getCurrentModeOwner } from "./store.js";
+import { clearMapModeState, getCurrentModeOwner, getMode, modeStore } from "./store.js";
 import { UseMapModeReturn, useMapMode } from "./use-map-mode.js";
 import { MapModeEventType, ModeChangeAuthorizationEvent, ModeChangeAuthorizationPayload, ModeChangeDecisionEvent, ModeChangeDecisionPayload, ModeChangeRequestEvent, ModeChangeRequestPayload, ModeChangedEvent, ModeChangedPayload } from "./types.js";
-export { type MapModeEventType, MapModeEvents, MapModeEventsNamespace, type ModeChangeAuthorizationEvent, type ModeChangeAuthorizationPayload, type ModeChangeDecisionEvent, type ModeChangeDecisionPayload, type ModeChangeRequestEvent, type ModeChangeRequestPayload, type ModeChangedEvent, type ModeChangedPayload, type UseMapModeReturn, clearMapModeState, getCurrentModeOwner, useMapMode };
+export { type MapModeEventType, MapModeEvents, MapModeEventsNamespace, type ModeChangeAuthorizationEvent, type ModeChangeAuthorizationPayload, type ModeChangeDecisionEvent, type ModeChangeDecisionPayload, type ModeChangeRequestEvent, type ModeChangeRequestPayload, type ModeChangedEvent, type ModeChangedPayload, type UseMapModeReturn, clearMapModeState, getCurrentModeOwner, getMode, modeStore, useMapMode };

package/dist/map-mode/index.js

@@ -12,7 +12,7 @@
 
 
 import { MapModeEvents, MapModeEventsNamespace } from "./events.js";
-import { clearMapModeState, getCurrentModeOwner } from "./store.js";
+import { clearMapModeState, getCurrentModeOwner, getMode, modeStore } from "./store.js";
 import { useMapMode } from "./use-map-mode.js";
 
-export { MapModeEvents, MapModeEventsNamespace, clearMapModeState, getCurrentModeOwner, useMapMode };
+export { MapModeEvents, MapModeEventsNamespace, clearMapModeState, getCurrentModeOwner, getMode, modeStore, useMapMode };

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

@@ -10,62 +10,61 @@
  * governing permissions and limitations under the License.
  */
 
+import { MapStore } from "../shared/create-map-store.js";
 import { UniqueId } from "@accelint/core";
 
 //#region src/map-mode/store.d.ts
 /**
- * Creates or retrieves a cached subscription function for a given instanceId.
- * Uses a fan-out pattern: 1 bus listener -> N React subscribers.
- * Automatically cleans up map mode state when the last subscriber unsubscribes.
- *
- * @param instanceId - The unique identifier for the map mode instance
- * @returns A subscription function for useSyncExternalStore
+ * Internal type for tracking pending authorization requests.
  */
-declare function getOrCreateSubscription(instanceId: UniqueId): (onStoreChange: () => void) => () => void;
+type PendingRequest = {
+  authId: string;
+  desiredMode: string;
+  currentMode: string;
+  requestOwner: string;
+};
 /**
- * Creates or retrieves a cached snapshot function for a given instanceId.
- * The string returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.
- *
- * @param instanceId - The unique identifier for the map mode instance
- * @returns A snapshot function for useSyncExternalStore
+ * State shape for map mode
  */
-declare function getOrCreateSnapshot(instanceId: UniqueId): () => string;
+type MapModeState = {
+  mode: string;
+  modeOwners: Map<string, string>;
+  pendingRequests: Map<string, PendingRequest>;
+};
 /**
- * Creates or retrieves a cached server snapshot function for a given instanceId.
- * Server snapshots always return the default mode since mode state is client-only.
- * Required for SSR/RSC compatibility with useSyncExternalStore.
- *
- * @param instanceId - The unique identifier for the map mode instance
- * @returns A server snapshot function for useSyncExternalStore
+ * Actions for map mode
  */
-declare function getOrCreateServerSnapshot(instanceId: UniqueId): () => string;
+type MapModeActions = {
+  /** Request a mode change */
+  requestModeChange: (desiredMode: string, requestOwner: string) => void;
+};
 /**
- * Creates or retrieves a cached requestModeChange function for a given instanceId.
- * This maintains referential stability for the function reference.
- *
- * @param instanceId - The unique identifier for the map mode instance
- * @returns A requestModeChange function for this instance
+ * Map mode store
  */
-declare function getOrCreateRequestModeChange(instanceId: UniqueId): (desiredMode: string, requestOwner: string) => void;
+declare const modeStore: MapStore<MapModeState, MapModeActions>;
+/**
+ * Get the current mode for a map instance
+ */
+declare function getMode(mapId: UniqueId): string;
+/**
+ * Hook for current mode value
+ */
+declare function useMode(mapId: UniqueId): string;
 /**
  * Get the owner of the current mode for a given map instance
  * @internal - For internal map-toolkit use only
  */
 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
+ */
+declare function isRegisteredModeOwner(instanceId: UniqueId, owner: string): boolean;
 /**
  * Manually clear map mode state for a specific instanceId.
- * 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 instanceId - The unique identifier for the map mode instance to clear
- *
- * @example
- * ```tsx
- * // Manual cleanup (rarely needed)
- * clearMapModeState('my-map-instance');
- * ```
  */
 declare function clearMapModeState(instanceId: UniqueId): void;
 //#endregion
-export { clearMapModeState, getCurrentModeOwner, getOrCreateRequestModeChange, getOrCreateServerSnapshot, getOrCreateSnapshot, getOrCreateSubscription };
+export { clearMapModeState, getCurrentModeOwner, getMode, isRegisteredModeOwner, modeStore, useMode };
 //# sourceMappingURL=store.d.ts.map