@accelint/map-toolkit 0.3.1 → 0.4.0

package/dist/map-cursor/store.js

@@ -0,0 +1,351 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+import { MapModeEvents } from "../map-mode/events.js";
+import { getCurrentModeOwner } from "../map-mode/store.js";
+import { MapCursorEvents } from "./events.js";
+import { Broadcast } from "@accelint/bus";
+
+//#region src/map-cursor/store.ts
+/**
+* Default cursor value
+*/
+const DEFAULT_CURSOR = "default";
+/**
+* Typed event bus instance for map cursor events.
+* Provides type-safe event emission and listening for all map cursor state changes.
+*/
+const mapCursorBus = Broadcast.getInstance();
+/**
+* Store for map cursor state keyed by instanceId
+*/
+const cursorStore = /* @__PURE__ */ new Map();
+/**
+* Track React component subscribers per instanceId (for fan-out notifications).
+* Each Set contains onStoreChange callbacks from useSyncExternalStore.
+*/
+const componentSubscribers = /* @__PURE__ */ new Map();
+/**
+* Cache of bus unsubscribe functions (1 per instanceId).
+* This ensures we only have one bus listener per map cursor instance, regardless of
+* how many React components subscribe to it.
+*/
+const busUnsubscribers = /* @__PURE__ */ new Map();
+/**
+* Cache of subscription functions per instanceId to avoid recreating on every render
+*/
+const subscriptionCache = /* @__PURE__ */ new Map();
+/**
+* Cache of snapshot functions per instanceId to maintain referential stability
+*/
+const snapshotCache = /* @__PURE__ */ new Map();
+/**
+* Cache of server snapshot functions per instanceId to maintain referential stability.
+* Server snapshots always return default cursor since cursor state is client-only.
+*/
+const serverSnapshotCache = /* @__PURE__ */ new Map();
+/**
+* Cache of requestCursorChange functions per instanceId to maintain referential stability
+*/
+const requestCursorChangeCache = /* @__PURE__ */ new Map();
+/**
+* Cache of clearCursor functions per instanceId to maintain referential stability
+*/
+const clearCursorCache = /* @__PURE__ */ new Map();
+/**
+* All state caches that need cleanup when an instance is removed
+*/
+const stateCaches = [
+	cursorStore,
+	componentSubscribers,
+	subscriptionCache,
+	snapshotCache,
+	serverSnapshotCache,
+	requestCursorChangeCache,
+	clearCursorCache
+];
+/**
+* Clear all cached state for a given instanceId
+*/
+function clearAllCaches(instanceId) {
+	stateCaches.map((cache) => cache.delete(instanceId));
+}
+/**
+* Get or create cursor state for a given instanceId
+*/
+function getOrCreateState(instanceId) {
+	if (!cursorStore.has(instanceId)) cursorStore.set(instanceId, {
+		cursorOwners: /* @__PURE__ */ new Map(),
+		currentCursor: null,
+		currentOwner: null
+	});
+	return cursorStore.get(instanceId);
+}
+/**
+* Get current cursor snapshot for a given instance (for useSyncExternalStore)
+*
+* Priority order:
+* 1. Mode owner's cursor (if exists and mode is owned)
+* 2. Most recent cursor (only if currentOwner still has an entry in storage)
+* 3. Default cursor
+*/
+function getSnapshot(instanceId) {
+	const state = cursorStore.get(instanceId);
+	if (!state) return DEFAULT_CURSOR;
+	const modeOwner = getCurrentModeOwner(instanceId);
+	if (modeOwner) {
+		const modeOwnerCursor = state.cursorOwners.get(modeOwner);
+		if (modeOwnerCursor) return modeOwnerCursor;
+	}
+	if (state.currentCursor && state.currentOwner) {
+		if (state.cursorOwners.has(state.currentOwner)) return state.currentCursor;
+	}
+	return DEFAULT_CURSOR;
+}
+/**
+* Notify all React subscribers for a given instanceId
+*/
+function notifySubscribers(instanceId) {
+	const subscribers = componentSubscribers.get(instanceId);
+	if (subscribers) for (const onStoreChange of subscribers) onStoreChange();
+}
+/**
+* Handle cursor change request for a given instance
+*/
+function handleCursorChangeRequest(instanceId, state, cursor, requestOwner) {
+	const previousCursor = getSnapshot(instanceId);
+	if (state.cursorOwners.get(requestOwner) === cursor) return;
+	state.cursorOwners.set(requestOwner, cursor);
+	const modeOwner = getCurrentModeOwner(instanceId);
+	if (!modeOwner || requestOwner === modeOwner) {
+		state.currentCursor = cursor;
+		state.currentOwner = requestOwner;
+		const newCursor = getSnapshot(instanceId);
+		if (previousCursor !== newCursor) {
+			mapCursorBus.emit(MapCursorEvents.changed, {
+				previousCursor,
+				currentCursor: newCursor,
+				owner: requestOwner,
+				id: instanceId
+			});
+			notifySubscribers(instanceId);
+		}
+	} else mapCursorBus.emit(MapCursorEvents.rejected, {
+		rejectedCursor: cursor,
+		rejectedOwner: requestOwner,
+		currentOwner: state.currentOwner || modeOwner || "unknown",
+		reason: "not-owner",
+		id: instanceId
+	});
+}
+/**
+* Ensures a single bus listener exists for the given instanceId.
+* All React subscribers will be notified via fan-out when the bus events fire.
+* This prevents creating N bus listeners for N React components.
+*
+* @param instanceId - The unique identifier for the map cursor instance
+*/
+function ensureBusListener(instanceId) {
+	if (busUnsubscribers.has(instanceId)) return;
+	const state = getOrCreateState(instanceId);
+	const unsubRequest = mapCursorBus.on(MapCursorEvents.changeRequest, (event) => {
+		const { cursor, owner: requestOwner, id } = event.payload;
+		if (id !== instanceId) return;
+		handleCursorChangeRequest(instanceId, state, cursor, requestOwner);
+	});
+	const unsubModeChange = Broadcast.getInstance().on(MapModeEvents.changed, (event) => {
+		if (event.payload.id !== instanceId) return;
+		const previousCursor = getSnapshot(instanceId);
+		if (event.payload.currentMode === "default" || event.payload.previousMode !== event.payload.currentMode) {
+			state.currentCursor = null;
+			state.currentOwner = null;
+			notifySubscribers(instanceId);
+		}
+		queueMicrotask(() => {
+			const newCursor = getSnapshot(instanceId);
+			if (previousCursor !== newCursor) {
+				const newModeOwner = getCurrentModeOwner(instanceId) || "system";
+				mapCursorBus.emit(MapCursorEvents.changed, {
+					previousCursor,
+					currentCursor: newCursor,
+					owner: newModeOwner,
+					id: instanceId
+				});
+				notifySubscribers(instanceId);
+			}
+		});
+	});
+	busUnsubscribers.set(instanceId, () => {
+		unsubRequest();
+		unsubModeChange();
+	});
+}
+/**
+* Cleans up the bus listener if no React subscribers remain.
+*
+* @param instanceId - The unique identifier for the map cursor instance
+*/
+function cleanupBusListenerIfNeeded(instanceId) {
+	const subscribers = componentSubscribers.get(instanceId);
+	if (!subscribers || subscribers.size === 0) {
+		const unsub = busUnsubscribers.get(instanceId);
+		if (unsub) {
+			unsub();
+			busUnsubscribers.delete(instanceId);
+		}
+		clearAllCaches(instanceId);
+	}
+}
+/**
+* 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 cursor state when the last subscriber unsubscribes.
+*
+* @param instanceId - The unique identifier for the map cursor instance
+* @returns A subscription function for useSyncExternalStore
+*/
+function getOrCreateSubscription(instanceId) {
+	const subscription = subscriptionCache.get(instanceId) ?? ((onStoreChange) => {
+		getOrCreateState(instanceId);
+		ensureBusListener(instanceId);
+		let subscriberSet = componentSubscribers.get(instanceId);
+		if (!subscriberSet) {
+			subscriberSet = /* @__PURE__ */ new Set();
+			componentSubscribers.set(instanceId, subscriberSet);
+		}
+		subscriberSet.add(onStoreChange);
+		return () => {
+			const currentSubscriberSet = componentSubscribers.get(instanceId);
+			if (currentSubscriberSet) currentSubscriberSet.delete(onStoreChange);
+			cleanupBusListenerIfNeeded(instanceId);
+		};
+	});
+	subscriptionCache.set(instanceId, subscription);
+	return subscription;
+}
+/**
+* Creates or retrieves a cached snapshot function for a given instanceId.
+* The cursor returned gets equality checked, so it needs to be stable or React re-renders unnecessarily.
+*
+* @param instanceId - The unique identifier for the map cursor instance
+* @returns A snapshot function for useSyncExternalStore
+*/
+function getOrCreateSnapshot(instanceId) {
+	const snapshot = snapshotCache.get(instanceId) ?? (() => getSnapshot(instanceId));
+	snapshotCache.set(instanceId, snapshot);
+	return snapshot;
+}
+/**
+* Creates or retrieves a cached server snapshot function for a given instanceId.
+* Server snapshots always return the default cursor since cursor state is client-only.
+* Required for SSR/RSC compatibility with useSyncExternalStore.
+*
+* @param instanceId - The unique identifier for the map cursor instance
+* @returns A server snapshot function for useSyncExternalStore
+*/
+function getOrCreateServerSnapshot(instanceId) {
+	const serverSnapshot = serverSnapshotCache.get(instanceId) ?? (() => DEFAULT_CURSOR);
+	serverSnapshotCache.set(instanceId, serverSnapshot);
+	return serverSnapshot;
+}
+/**
+* Creates or retrieves a cached requestCursorChange function for a given instanceId.
+* This maintains referential stability for the function reference.
+*
+* @param instanceId - The unique identifier for the map cursor instance
+* @returns A requestCursorChange function for this instance
+*/
+function getOrCreateRequestCursorChange(instanceId) {
+	const requestCursorChange = requestCursorChangeCache.get(instanceId) ?? ((cursor, owner) => {
+		const trimmedCursor = cursor.trim();
+		const trimmedOwner = owner.trim();
+		if (!trimmedCursor) throw new Error("requestCursorChange requires non-empty cursor");
+		if (!trimmedOwner) throw new Error("requestCursorChange requires non-empty owner");
+		mapCursorBus.emit(MapCursorEvents.changeRequest, {
+			cursor: trimmedCursor,
+			owner: trimmedOwner,
+			id: instanceId
+		});
+	});
+	requestCursorChangeCache.set(instanceId, requestCursorChange);
+	return requestCursorChange;
+}
+/**
+* Creates or retrieves a cached clearCursor function for a given instanceId.
+* This maintains referential stability for the function reference.
+*
+* @param instanceId - The unique identifier for the map cursor instance
+* @returns A clearCursor function for this instance
+*/
+function getOrCreateClearCursor(instanceId) {
+	const clearCursor = clearCursorCache.get(instanceId) ?? ((owner) => {
+		const state = cursorStore.get(instanceId);
+		if (!state) return;
+		const hadCursor = state.cursorOwners.has(owner);
+		state.cursorOwners.delete(owner);
+		if (state.currentOwner === owner) {
+			state.currentCursor = null;
+			state.currentOwner = null;
+		}
+		if (hadCursor) notifySubscribers(instanceId);
+	});
+	clearCursorCache.set(instanceId, clearCursor);
+	return clearCursor;
+}
+/**
+* Get the current cursor for a given instance (direct access, not reactive).
+* @internal - For internal map-toolkit use only
+*
+* @param instanceId - The unique identifier for the map instance
+* @returns The current cursor
+*/
+function getCursor(instanceId) {
+	return getSnapshot(instanceId);
+}
+/**
+* Manually clear all cursor 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 cursor instance to clear
+*
+* @example
+* ```tsx
+* // Manual cleanup (rarely needed)
+* clearCursorState('my-map-instance');
+* ```
+*/
+function clearCursorState(instanceId) {
+	const unsub = busUnsubscribers.get(instanceId);
+	if (unsub) {
+		unsub();
+		busUnsubscribers.delete(instanceId);
+	}
+	clearAllCaches(instanceId);
+}
+/** @deprecated Use module functions directly */
+function getOrCreateStore(id) {
+	return { getSnapshot: () => getSnapshot(id) };
+}
+/** @deprecated Use clearCursorState instead */
+function destroyStore(id) {
+	clearCursorState(id);
+}
+/** @deprecated Use direct function calls instead */
+function getStore(id) {
+	return { getSnapshot: () => getSnapshot(id) };
+}
+
+//#endregion
+export { clearCursorState, destroyStore, getCursor, getOrCreateClearCursor, getOrCreateRequestCursorChange, getOrCreateServerSnapshot, getOrCreateSnapshot, getOrCreateStore, getOrCreateSubscription, getStore };
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +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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"}

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

@@ -0,0 +1,81 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { Payload } from "@accelint/bus";
+import React from "react";
+import { UniqueId } from "@accelint/core";
+
+//#region src/map-cursor/types.d.ts
+/**
+ * CSS cursor type from React's CSSProperties
+ * Includes all standard cursor keywords and custom url() syntax
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/cursor
+ */
+type CSSCursorType = NonNullable<React.CSSProperties['cursor']>;
+/**
+ * Payload for cursor change request events
+ */
+type CursorChangeRequestPayload = {
+  /** The desired cursor CSS string */
+  cursor: CSSCursorType;
+  /** The unique identifier of the requester */
+  owner: string;
+  /** The map instance ID this request targets */
+  id: UniqueId;
+};
+/**
+ * Payload for cursor changed events
+ */
+type CursorChangedPayload = {
+  /** The previous cursor value */
+  previousCursor: CSSCursorType;
+  /** The new cursor value */
+  currentCursor: CSSCursorType;
+  /** The owner of the new cursor */
+  owner: string;
+  /** The map instance ID */
+  id: UniqueId;
+};
+/**
+ * Payload for cursor rejection events
+ */
+type CursorRejectionPayload = {
+  /** The cursor that was rejected */
+  rejectedCursor: CSSCursorType;
+  /** The owner whose request was rejected */
+  rejectedOwner: string;
+  /** The current cursor owner */
+  currentOwner: string;
+  /** Reason for rejection */
+  reason: string;
+  /** The map instance ID */
+  id: UniqueId;
+};
+/**
+ * Typed event for cursor change request
+ */
+type CursorChangeRequestEvent = Payload<'cursor:change-request', CursorChangeRequestPayload>;
+/**
+ * Typed event for cursor changed
+ */
+type CursorChangedEvent = Payload<'cursor:changed', CursorChangedPayload>;
+/**
+ * Typed event for cursor rejected
+ */
+type CursorRejectedEvent = Payload<'cursor:rejected', CursorRejectionPayload>;
+/**
+ * Union of all cursor event payloads
+ */
+type MapCursorEventType = CursorChangeRequestEvent | CursorChangedEvent | CursorRejectedEvent;
+//#endregion
+export { CSSCursorType, CursorChangeRequestEvent, CursorChangeRequestPayload, CursorChangedEvent, CursorChangedPayload, CursorRejectedEvent, CursorRejectionPayload, MapCursorEventType };
+//# sourceMappingURL=types.d.ts.map

package/dist/map-cursor/types.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+

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

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { CSSCursorType } from "./types.js";
+import { UniqueId } from "@accelint/core";
+
+//#region src/map-cursor/use-map-cursor.d.ts
+/**
+ * Return value for the useMapCursor hook
+ */
+type UseMapCursorReturn = {
+  /** The current active cursor */
+  cursor: CSSCursorType;
+  /** Function to request a cursor change with ownership */
+  requestCursorChange: (cursor: CSSCursorType, requestOwner: string) => void;
+  /** Function to clear cursor for an owner */
+  clearCursor: (owner: string) => void;
+};
+/**
+ * Hook to access the map cursor state and actions.
+ *
+ * This hook uses `useSyncExternalStore` to subscribe to map cursor state changes,
+ * providing concurrent-safe cursor state updates. Uses a fan-out pattern where
+ * a single bus listener per map instance notifies N React component subscribers.
+ *
+ * **Owner-based Priority System:**
+ * - Mode owners (from MapModeStore) have highest priority
+ * - Non-owners can set cursors only in default/ownerless modes
+ * - Rejected requests emit events with rejection reasons
+ *
+ * @param id - Optional map instance ID. If not provided, will use the ID from `MapContext`.
+ * @returns The current cursor, requestCursorChange function, and clearCursor function
+ * @throws Error if no `id` is provided and hook is used outside of `MapProvider`
+ *
+ * @example
+ * ```tsx
+ * // Inside MapProvider (within BaseMap children)
+ * function CustomDeckLayer() {
+ *   const { cursor, requestCursorChange, clearCursor } = useMapCursor();
+ *
+ *   const handleHover = (info: PickingInfo) => {
+ *     if (info.object) {
+ *       requestCursorChange('pointer', 'custom-layer-id');
+ *     } else {
+ *       clearCursor('custom-layer-id');
+ *     }
+ *   };
+ *
+ *   return <ScatterplotLayer onHover={handleHover} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Outside MapProvider - pass id directly
+ * function ExternalControl({ mapId }: { mapId: UniqueId }) {
+ *   const { cursor, requestCursorChange } = useMapCursor(mapId);
+ *
+ *   return (
+ *     <button onClick={() => requestCursorChange('crosshair', 'external-control')}>
+ *       Set Crosshair (current: {cursor})
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useMapCursor(id?: UniqueId): UseMapCursorReturn;
+/**
+ * Hook to automatically manage cursor for a component's lifecycle.
+ *
+ * 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
+ * @param owner - The owner identifier
+ * @param id - Optional map instance ID
+ *
+ * @example
+ * ```tsx
+ * function DrawingMode() {
+ *   useMapCursorEffect('crosshair', 'drawing-mode');
+ *
+ *   return <div>Drawing mode active with crosshair cursor</div>;
+ * }
+ * ```
+ */
+declare function useMapCursorEffect(cursor: CSSCursorType, owner: string, id?: UniqueId): void;
+//#endregion
+export { UseMapCursorReturn, useMapCursor, useMapCursorEffect };
+//# sourceMappingURL=use-map-cursor.d.ts.map