@accelint/map-toolkit 0.3.1 → 0.4.1

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

@@ -0,0 +1,116 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+'use client';
+
+import { getOrCreateClearCursor, getOrCreateRequestCursorChange, getOrCreateServerSnapshot, getOrCreateSnapshot, getOrCreateSubscription } from "./store.js";
+import { MapContext } from "../deckgl/base-map/provider.js";
+import { useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+
+//#region src/map-cursor/use-map-cursor.ts
+/**
+* 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>
+*   );
+* }
+* ```
+*/
+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));
+	return useMemo(() => ({
+		cursor,
+		requestCursorChange: getOrCreateRequestCursorChange(actualId),
+		clearCursor: getOrCreateClearCursor(actualId)
+	}), [cursor, actualId]);
+}
+/**
+* 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>;
+* }
+* ```
+*/
+function useMapCursorEffect(cursor, owner, id) {
+	const { requestCursorChange, clearCursor } = useMapCursor(id);
+	useEffect(() => {
+		requestCursorChange(cursor, owner);
+		return () => {
+			clearCursor(owner);
+		};
+	}, [
+		cursor,
+		owner,
+		requestCursorChange,
+		clearCursor
+	]);
+}
+
+//#endregion
+export { useMapCursor, useMapCursorEffect };
+//# sourceMappingURL=use-map-cursor.js.map

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

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

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

@@ -1,3 +1,4 @@
+//#region src/map-mode/events.d.ts
 /**
  * Namespace prefix for all map mode events.
  */
@@ -24,14 +25,15 @@ declare const MapModeEventsNamespace = "map-mode";
  * ```
  */
 declare const MapModeEvents: {
-    /** Emitted when the map mode has successfully changed */
-    readonly changed: "map-mode:changed";
-    /** Emitted when a component requests a mode change */
-    readonly changeRequest: "map-mode:change:request";
-    /** Emitted when authorization is required for a mode change */
-    readonly changeAuthorization: "map-mode:change:authorization";
-    /** Emitted when an authorization decision is made (approve/reject) */
-    readonly changeDecision: "map-mode:change:decision";
+  /** Emitted when the map mode has successfully changed */
+  readonly changed: "map-mode:changed";
+  /** Emitted when a component requests a mode change */
+  readonly changeRequest: "map-mode:change:request";
+  /** Emitted when authorization is required for a mode change */
+  readonly changeAuthorization: "map-mode:change:authorization";
+  /** Emitted when an authorization decision is made (approve/reject) */
+  readonly changeDecision: "map-mode:change:decision";
 };
-
+//#endregion
 export { MapModeEvents, MapModeEventsNamespace };
+//# sourceMappingURL=events.d.ts.map

package/dist/map-mode/events.js

@@ -1,15 +1,49 @@
+/*
+ * 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.
+ */
+
+
+//#region src/map-mode/events.ts
+/**
+* Namespace prefix for all map mode events.
+*/
 const MapModeEventsNamespace = "map-mode";
+/**
+* Event type constants for map mode state management.
+*
+* These events are emitted through the `@accelint/bus` event bus to coordinate
+* map mode changes across components in a decoupled manner.
+*
+* @example
+* ```ts
+* import { useOn, useEmit } from '@accelint/bus/react';
+* import { MapModeEvents } from '@accelint/map-toolkit/map-mode';
+*
+* // Listen for mode changes
+* useOn(MapModeEvents.changed, (event) => {
+*   console.log('Mode changed to:', event.payload.currentMode);
+* });
+*
+* // Emit a decision
+* const emitDecision = useEmit(MapModeEvents.changeDecision);
+* emitDecision({ authId, approved: true, owner: 'my-id', id });
+* ```
+*/
 const MapModeEvents = {
-  /** Emitted when the map mode has successfully changed */
-  changed: `${MapModeEventsNamespace}:changed`,
-  /** Emitted when a component requests a mode change */
-  changeRequest: `${MapModeEventsNamespace}:change:request`,
-  /** Emitted when authorization is required for a mode change */
-  changeAuthorization: `${MapModeEventsNamespace}:change:authorization`,
-  /** Emitted when an authorization decision is made (approve/reject) */
-  changeDecision: `${MapModeEventsNamespace}:change:decision`
+	changed: `${MapModeEventsNamespace}:changed`,
+	changeRequest: `${MapModeEventsNamespace}:change:request`,
+	changeAuthorization: `${MapModeEventsNamespace}:change:authorization`,
+	changeDecision: `${MapModeEventsNamespace}:change:decision`
 };
 
+//#endregion
 export { MapModeEvents, MapModeEventsNamespace };
-//# sourceMappingURL=events.js.map
 //# sourceMappingURL=events.js.map

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

@@ -1 +1 @@
-{"version":3,"sources":["../../src/map-mode/events.ts"],"names":[],"mappings":"AAeO,MAAM,sBAAA,GAAyB;AAuB/B,MAAM,aAAA,GAAgB;AAAA;AAAA,EAE3B,OAAA,EAAS,GAAG,sBAAsB,CAAA,QAAA,CAAA;AAAA;AAAA,EAElC,aAAA,EAAe,GAAG,sBAAsB,CAAA,eAAA,CAAA;AAAA;AAAA,EAExC,mBAAA,EAAqB,GAAG,sBAAsB,CAAA,qBAAA,CAAA;AAAA;AAAA,EAE9C,cAAA,EAAgB,GAAG,sBAAsB,CAAA,gBAAA;AAC3C","file":"events.js","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 * Namespace prefix for all map mode events.\n */\nexport const MapModeEventsNamespace = 'map-mode';\n\n/**\n * Event type constants for map mode state management.\n *\n * These events are emitted through the `@accelint/bus` event bus to coordinate\n * map mode changes across components in a decoupled manner.\n *\n * @example\n * ```ts\n * import { useOn, useEmit } from '@accelint/bus/react';\n * import { MapModeEvents } from '@accelint/map-toolkit/map-mode';\n *\n * // Listen for mode changes\n * useOn(MapModeEvents.changed, (event) => {\n *   console.log('Mode changed to:', event.payload.currentMode);\n * });\n *\n * // Emit a decision\n * const emitDecision = useEmit(MapModeEvents.changeDecision);\n * emitDecision({ authId, approved: true, owner: 'my-id', id });\n * ```\n */\nexport const MapModeEvents = {\n  /** Emitted when the map mode has successfully changed */\n  changed: `${MapModeEventsNamespace}:changed`,\n  /** Emitted when a component requests a mode change */\n  changeRequest: `${MapModeEventsNamespace}:change:request`,\n  /** Emitted when authorization is required for a mode change */\n  changeAuthorization: `${MapModeEventsNamespace}:change:authorization`,\n  /** Emitted when an authorization decision is made (approve/reject) */\n  changeDecision: `${MapModeEventsNamespace}:change:decision`,\n} as const;\n"]}
+{"version":3,"file":"events.js","names":[],"sources":["../../src/map-mode/events.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 * Namespace prefix for all map mode events.\n */\nexport const MapModeEventsNamespace = 'map-mode';\n\n/**\n * Event type constants for map mode state management.\n *\n * These events are emitted through the `@accelint/bus` event bus to coordinate\n * map mode changes across components in a decoupled manner.\n *\n * @example\n * ```ts\n * import { useOn, useEmit } from '@accelint/bus/react';\n * import { MapModeEvents } from '@accelint/map-toolkit/map-mode';\n *\n * // Listen for mode changes\n * useOn(MapModeEvents.changed, (event) => {\n *   console.log('Mode changed to:', event.payload.currentMode);\n * });\n *\n * // Emit a decision\n * const emitDecision = useEmit(MapModeEvents.changeDecision);\n * emitDecision({ authId, approved: true, owner: 'my-id', id });\n * ```\n */\nexport const MapModeEvents = {\n  /** Emitted when the map mode has successfully changed */\n  changed: `${MapModeEventsNamespace}:changed`,\n  /** Emitted when a component requests a mode change */\n  changeRequest: `${MapModeEventsNamespace}:change:request`,\n  /** Emitted when authorization is required for a mode change */\n  changeAuthorization: `${MapModeEventsNamespace}:change:authorization`,\n  /** Emitted when an authorization decision is made (approve/reject) */\n  changeDecision: `${MapModeEventsNamespace}:change:decision`,\n} as const;\n"],"mappings":";;;;;;;;;;;;;;;;;AAeA,MAAa,yBAAyB;;;;;;;;;;;;;;;;;;;;;;AAuBtC,MAAa,gBAAgB;CAE3B,SAAS,GAAG,uBAAuB;CAEnC,eAAe,GAAG,uBAAuB;CAEzC,qBAAqB,GAAG,uBAAuB;CAE/C,gBAAgB,GAAG,uBAAuB;CAC3C"}

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

@@ -1,6 +1,17 @@
-export { MapModeEvents, MapModeEventsNamespace } from './events.js';
-export { clearMapModeState, getCurrentModeOwner } from './store.js';
-export { UseMapModeReturn, useMapMode } from './use-map-mode.js';
-export { MapModeEventType, ModeChangeAuthorizationEvent, ModeChangeAuthorizationPayload, ModeChangeDecisionEvent, ModeChangeDecisionPayload, ModeChangeRequestEvent, ModeChangeRequestPayload, ModeChangedEvent, ModeChangedPayload } from './types.js';
-import '@accelint/core';
-import '@accelint/bus';
+/*
+ * 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, MapModeEventsNamespace } from "./events.js";
+import { clearMapModeState, getCurrentModeOwner } 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 };

package/dist/map-mode/index.js

@@ -1,5 +1,18 @@
-export { MapModeEvents, MapModeEventsNamespace } from './events.js';
-export { clearMapModeState, getCurrentModeOwner } from './store.js';
-export { useMapMode } from './use-map-mode.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map
+/*
+ * 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, MapModeEventsNamespace } from "./events.js";
+import { clearMapModeState, getCurrentModeOwner } from "./store.js";
+import { useMapMode } from "./use-map-mode.js";
+
+export { MapModeEvents, MapModeEventsNamespace, clearMapModeState, getCurrentModeOwner, useMapMode };

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

@@ -1,5 +1,18 @@
-import { UniqueId } from '@accelint/core';
+/*
+ * 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 { 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.
@@ -17,6 +30,15 @@ declare function getOrCreateSubscription(instanceId: UniqueId): (onStoreChange:
  * @returns A snapshot function for useSyncExternalStore
  */
 declare function getOrCreateSnapshot(instanceId: UniqueId): () => string;
+/**
+ * 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
+ */
+declare function getOrCreateServerSnapshot(instanceId: UniqueId): () => string;
 /**
  * Creates or retrieves a cached requestModeChange function for a given instanceId.
  * This maintains referential stability for the function reference.
@@ -44,5 +66,6 @@ declare function getCurrentModeOwner(instanceId: UniqueId): string | undefined;
  * ```
  */
 declare function clearMapModeState(instanceId: UniqueId): void;
-
-export { clearMapModeState, getCurrentModeOwner, getOrCreateRequestModeChange, getOrCreateSnapshot, getOrCreateSubscription };
+//#endregion
+export { clearMapModeState, getCurrentModeOwner, getOrCreateRequestModeChange, getOrCreateServerSnapshot, getOrCreateSnapshot, getOrCreateSubscription };
+//# sourceMappingURL=store.d.ts.map