@accelint/map-toolkit 0.1.0 → 0.2.0

package/dist/map-mode/store.js

@@ -0,0 +1,327 @@
+import { Broadcast } from '@accelint/bus';
+import { uuid } from '@accelint/core';
+import { MapModeEvents } from './events.js';
+
+const DEFAULT_MODE = "default";
+const mapModeBus = Broadcast.getInstance();
+class MapModeStore {
+  constructor(id) {
+    this.id = id;
+    this.id = id;
+    this.setupEventListeners();
+  }
+  mode = DEFAULT_MODE;
+  defaultMode = DEFAULT_MODE;
+  modeOwners = /* @__PURE__ */ new Map();
+  pendingRequests = /* @__PURE__ */ new Map();
+  listeners = /* @__PURE__ */ new Set();
+  bus = mapModeBus;
+  unsubscribers = [];
+  /**
+   * Get current mode snapshot (for useSyncExternalStore)
+   */
+  getSnapshot = () => {
+    return this.mode;
+  };
+  /**
+   * Subscribe to mode changes (for useSyncExternalStore)
+   */
+  subscribe = (listener) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+  /**
+   * Request a mode change
+   *
+   * If the mode change can be auto-accepted (no ownership conflicts), the mode changes immediately.
+   * Otherwise, an authorization request is emitted and stored as a pending request.
+   *
+   * **Important**: If the requester already has a pending authorization request, it will be replaced
+   * with this new request. Only one pending request per requester is maintained at a time.
+   *
+   * @param desiredMode - The mode to switch to (automatically trimmed of whitespace)
+   * @param requestOwner - Unique identifier of the component requesting the change (automatically trimmed of whitespace)
+   * @throws Error if either parameter is empty or whitespace-only
+   *
+   * @example
+   * ```ts
+   * // First request from 'drawing-tool'
+   * store.requestModeChange('drawing', 'drawing-tool');
+   * // → Creates pending request with authId 'abc-123'
+   *
+   * // Second request from same 'drawing-tool' before first is resolved
+   * store.requestModeChange('measuring', 'drawing-tool');
+   * // → Replaces pending request, new authId 'def-456', old 'abc-123' is discarded
+   * ```
+   */
+  requestModeChange = (desiredMode, requestOwner) => {
+    const trimmedDesiredMode = desiredMode.trim();
+    const trimmedRequestOwner = requestOwner.trim();
+    if (!trimmedDesiredMode) {
+      throw new Error("requestModeChange requires non-empty desiredMode");
+    }
+    if (!trimmedRequestOwner) {
+      throw new Error("requestModeChange requires non-empty requestOwner");
+    }
+    this.bus.emit(MapModeEvents.changeRequest, {
+      desiredMode: trimmedDesiredMode,
+      owner: trimmedRequestOwner,
+      id: this.id
+    });
+  };
+  /**
+   * Notify all subscribers of state change
+   */
+  notify() {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+  /**
+   * Setup event listeners for bus events
+   *
+   * Note: Event listeners remain active even after early returns in handlers.
+   * This is by design - cleanup happens in destroy() which is called automatically
+   * by MapProvider on unmount. Consumers don't need to manually manage cleanup.
+   */
+  setupEventListeners() {
+    const unsubRequest = this.bus.on(MapModeEvents.changeRequest, (event) => {
+      const { desiredMode, owner: requestOwner, id } = event.payload;
+      if (id !== this.id || desiredMode === this.mode) {
+        return;
+      }
+      this.handleModeChangeRequest(desiredMode, requestOwner);
+    });
+    this.unsubscribers.push(unsubRequest);
+    const unsubDecision = this.bus.on(MapModeEvents.changeDecision, (event) => {
+      const { id, approved, authId, owner } = event.payload;
+      if (id !== this.id) {
+        return;
+      }
+      this.handleAuthorizationDecision({ approved, authId, owner });
+    });
+    this.unsubscribers.push(unsubDecision);
+    const unsubChanged = this.bus.on(MapModeEvents.changed, (event) => {
+      const { currentMode, previousMode, id } = event.payload;
+      if (id !== this.id) {
+        return;
+      }
+      if (currentMode === this.defaultMode && this.pendingRequests.size > 0) {
+        this.handlePendingRequestsOnDefaultMode(previousMode);
+      }
+    });
+    this.unsubscribers.push(unsubChanged);
+  }
+  /**
+   * Determine if a mode change request should be auto-accepted without authorization
+   */
+  shouldAutoAcceptRequest(desiredMode, requestOwner, currentModeOwner, desiredModeOwner) {
+    if (desiredMode === this.defaultMode && requestOwner === currentModeOwner) {
+      return true;
+    }
+    if (requestOwner === currentModeOwner) {
+      return true;
+    }
+    if (!(currentModeOwner || desiredModeOwner)) {
+      return true;
+    }
+    if (this.mode === this.defaultMode && requestOwner === desiredModeOwner) {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Handle mode change request logic
+   */
+  handleModeChangeRequest(desiredMode, requestOwner) {
+    const currentModeOwner = this.modeOwners.get(this.mode);
+    const desiredModeOwner = this.modeOwners.get(desiredMode);
+    if (this.shouldAutoAcceptRequest(
+      desiredMode,
+      requestOwner,
+      currentModeOwner,
+      desiredModeOwner
+    )) {
+      this.setMode(desiredMode);
+      if (desiredMode !== this.defaultMode && !desiredModeOwner) {
+        this.modeOwners.set(desiredMode, requestOwner);
+      }
+      this.pendingRequests.delete(requestOwner);
+      return;
+    }
+    const authId = uuid();
+    this.pendingRequests.set(requestOwner, {
+      authId,
+      desiredMode,
+      currentMode: this.mode,
+      requestOwner
+    });
+    this.bus.emit(MapModeEvents.changeAuthorization, {
+      authId,
+      desiredMode,
+      currentMode: this.mode,
+      id: this.id
+    });
+  }
+  /**
+   * Handle authorization decision
+   *
+   * Processes approval/rejection decisions from mode owners. Only the current mode's owner
+   * can make authorization decisions. If a decision comes from a non-owner, a warning is
+   * logged and the decision is ignored to prevent unauthorized mode changes.
+   *
+   * @param payload - The authorization decision containing authId, approved status, and owner
+   */
+  handleAuthorizationDecision(payload) {
+    const { approved, authId, owner: decisionOwner } = payload;
+    const currentModeOwner = this.modeOwners.get(this.mode);
+    if (decisionOwner !== currentModeOwner) {
+      console.warn(
+        `[MapMode] Authorization decision from "${decisionOwner}" ignored - not the owner of mode "${this.mode}" (owner: ${currentModeOwner || "none"})`
+      );
+      return;
+    }
+    let matchingRequestOwner = null;
+    let matchingRequest = null;
+    for (const [requestOwner, request] of this.pendingRequests.entries()) {
+      if (request.authId === authId) {
+        matchingRequestOwner = requestOwner;
+        matchingRequest = request;
+        break;
+      }
+    }
+    if (!(matchingRequest && matchingRequestOwner)) {
+      return;
+    }
+    if (approved) {
+      this.approveRequestAndRejectOthers(
+        matchingRequest,
+        authId,
+        decisionOwner,
+        "",
+        false
+      );
+    } else {
+      this.pendingRequests.delete(matchingRequestOwner);
+    }
+  }
+  /**
+   * Approve a request and reject all others
+   */
+  approveRequestAndRejectOthers(approvedRequest, excludeAuthId, decisionOwner, reason, emitApproval) {
+    const requestsToReject = [];
+    for (const request of this.pendingRequests.values()) {
+      if (request.authId !== excludeAuthId) {
+        requestsToReject.push(request);
+      }
+    }
+    this.pendingRequests.clear();
+    this.setMode(approvedRequest.desiredMode);
+    if (approvedRequest.desiredMode !== this.defaultMode) {
+      this.modeOwners.set(
+        approvedRequest.desiredMode,
+        approvedRequest.requestOwner
+      );
+    }
+    if (emitApproval) {
+      this.bus.emit(MapModeEvents.changeDecision, {
+        authId: approvedRequest.authId,
+        approved: true,
+        owner: decisionOwner,
+        reason,
+        id: this.id
+      });
+    }
+    for (const request of requestsToReject) {
+      this.bus.emit(MapModeEvents.changeDecision, {
+        authId: request.authId,
+        approved: false,
+        owner: decisionOwner,
+        reason: "Request auto-rejected because another request was approved",
+        id: this.id
+      });
+    }
+  }
+  /**
+   * Handle pending requests when returning to default mode
+   */
+  handlePendingRequestsOnDefaultMode(previousMode) {
+    const firstEntry = Array.from(this.pendingRequests.values())[0];
+    if (!firstEntry) {
+      return;
+    }
+    const previousModeOwner = this.modeOwners.get(previousMode);
+    if (!previousModeOwner) {
+      return;
+    }
+    if (firstEntry.desiredMode === this.defaultMode) {
+      const allRequests = Array.from(this.pendingRequests.values());
+      this.pendingRequests.clear();
+      for (const request of allRequests) {
+        this.bus.emit(MapModeEvents.changeDecision, {
+          authId: request.authId,
+          approved: false,
+          owner: previousModeOwner,
+          reason: "Request rejected - already in requested mode",
+          id: this.id
+        });
+      }
+    } else {
+      this.approveRequestAndRejectOthers(
+        firstEntry,
+        firstEntry.authId,
+        previousModeOwner,
+        "Auto-accepted when mode owner returned to default",
+        true
+      );
+    }
+  }
+  /**
+   * Set mode and notify listeners
+   */
+  setMode(newMode) {
+    const previousMode = this.mode;
+    this.mode = newMode;
+    this.bus.emit(MapModeEvents.changed, {
+      previousMode,
+      currentMode: newMode,
+      id: this.id
+    });
+    this.notify();
+  }
+  /**
+   * Clean up store resources
+   */
+  destroy() {
+    for (const unsubscribe of this.unsubscribers) {
+      unsubscribe();
+    }
+    this.unsubscribers.length = 0;
+    this.modeOwners.clear();
+    this.pendingRequests.clear();
+    this.listeners.clear();
+  }
+}
+const storeRegistry = /* @__PURE__ */ new Map();
+function getOrCreateStore(id) {
+  if (!storeRegistry.has(id)) {
+    storeRegistry.set(id, new MapModeStore(id));
+  }
+  return storeRegistry.get(id);
+}
+function destroyStore(id) {
+  const store = storeRegistry.get(id);
+  if (store) {
+    store.destroy();
+    storeRegistry.delete(id);
+  }
+}
+function getStore(id) {
+  return storeRegistry.get(id);
+}
+
+export { MapModeStore, destroyStore, getOrCreateStore, getStore };
+//# sourceMappingURL=store.js.map
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/map-mode/store.ts"],"names":[],"mappings":"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","file":"store.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\nimport { Broadcast } from '@accelint/bus';\nimport { uuid } from '@accelint/core';\nimport { MapModeEvents } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { MapModeEventType, ModeChangeDecisionPayload } from './types';\n\nconst DEFAULT_MODE = 'default';\n\n/**\n * Typed event bus instance for map mode events.\n * Provides type-safe event emission and listening for all map mode state changes.\n */\nconst mapModeBus = Broadcast.getInstance<MapModeEventType>();\n\n/**\n * Internal type for tracking pending authorization requests.\n * @internal\n */\ntype PendingRequest = {\n  authId: string;\n  desiredMode: string;\n  currentMode: string;\n  requestOwner: string;\n};\n\n/**\n * External store for managing map mode state.\n *\n * This store implements the observable pattern for use with React's `useSyncExternalStore` hook.\n * It manages all mode state, ownership tracking, authorization flow, and event bus communication\n * outside of React's component tree.\n *\n * Each store instance is identified by a unique `id` and operates independently,\n * enabling scenarios with multiple isolated map instances (e.g., main map + minimap).\n * Stores communicate via the event bus and filter events by `id` to ensure isolation.\n *\n * The store always initializes in 'default' mode and does not accept a custom default mode.\n *\n * @see {getOrCreateStore} - Creates or retrieves a store for a given map instance\n * @see {destroyStore} - Destroys a store and cleans up its resources\n */\nexport class MapModeStore {\n  private mode = DEFAULT_MODE;\n  private readonly defaultMode = DEFAULT_MODE;\n  private readonly modeOwners = new Map<string, string>();\n  private readonly pendingRequests = new Map<string, PendingRequest>();\n  private readonly listeners = new Set<() => void>();\n  private readonly bus = mapModeBus;\n  private readonly unsubscribers: Array<() => void> = [];\n\n  constructor(private readonly id: UniqueId) {\n    this.id = id;\n    // Subscribe to bus events\n    this.setupEventListeners();\n  }\n\n  /**\n   * Get current mode snapshot (for useSyncExternalStore)\n   */\n  getSnapshot = (): string => {\n    return this.mode;\n  };\n\n  /**\n   * Subscribe to mode changes (for useSyncExternalStore)\n   */\n  subscribe = (listener: () => void): (() => void) => {\n    this.listeners.add(listener);\n    return () => {\n      this.listeners.delete(listener);\n    };\n  };\n\n  /**\n   * Request a mode change\n   *\n   * If the mode change can be auto-accepted (no ownership conflicts), the mode changes immediately.\n   * Otherwise, an authorization request is emitted and stored as a pending request.\n   *\n   * **Important**: If the requester already has a pending authorization request, it will be replaced\n   * with this new request. Only one pending request per requester is maintained at a time.\n   *\n   * @param desiredMode - The mode to switch to (automatically trimmed of whitespace)\n   * @param requestOwner - Unique identifier of the component requesting the change (automatically trimmed of whitespace)\n   * @throws Error if either parameter is empty or whitespace-only\n   *\n   * @example\n   * ```ts\n   * // First request from 'drawing-tool'\n   * store.requestModeChange('drawing', 'drawing-tool');\n   * // → Creates pending request with authId 'abc-123'\n   *\n   * // Second request from same 'drawing-tool' before first is resolved\n   * store.requestModeChange('measuring', 'drawing-tool');\n   * // → Replaces pending request, new authId 'def-456', old 'abc-123' is discarded\n   * ```\n   */\n  requestModeChange = (desiredMode: string, requestOwner: string): void => {\n    const trimmedDesiredMode = desiredMode.trim();\n    const trimmedRequestOwner = requestOwner.trim();\n\n    if (!trimmedDesiredMode) {\n      throw new Error('requestModeChange requires non-empty desiredMode');\n    }\n    if (!trimmedRequestOwner) {\n      throw new Error('requestModeChange requires non-empty requestOwner');\n    }\n\n    this.bus.emit(MapModeEvents.changeRequest, {\n      desiredMode: trimmedDesiredMode,\n      owner: trimmedRequestOwner,\n      id: this.id,\n    });\n  };\n\n  /**\n   * Notify all subscribers of state change\n   */\n  private notify(): void {\n    for (const listener of this.listeners) {\n      listener();\n    }\n  }\n\n  /**\n   * Setup event listeners for bus events\n   *\n   * Note: Event listeners remain active even after early returns in handlers.\n   * This is by design - cleanup happens in destroy() which is called automatically\n   * by MapProvider on unmount. Consumers don't need to manually manage cleanup.\n   */\n  private setupEventListeners(): void {\n    // Listen for mode change requests\n    const unsubRequest = this.bus.on(MapModeEvents.changeRequest, (event) => {\n      const { desiredMode, owner: requestOwner, id } = event.payload;\n\n      // Filter: only handle if targeted at this map\n      if (id !== this.id || desiredMode === this.mode) {\n        return;\n      }\n\n      this.handleModeChangeRequest(desiredMode, requestOwner);\n    });\n    this.unsubscribers.push(unsubRequest);\n\n    // Listen for authorization decisions\n    const unsubDecision = this.bus.on(MapModeEvents.changeDecision, (event) => {\n      const { id, approved, authId, owner } = event.payload;\n\n      // Filter: only handle if targeted at this map\n      if (id !== this.id) {\n        return;\n      }\n\n      this.handleAuthorizationDecision({ approved, authId, owner });\n    });\n    this.unsubscribers.push(unsubDecision);\n\n    // Listen for mode changes to handle pending requests\n    const unsubChanged = this.bus.on(MapModeEvents.changed, (event) => {\n      const { currentMode, previousMode, id } = event.payload;\n\n      // Filter: only handle if targeted at this map\n      if (id !== this.id) {\n        return;\n      }\n\n      // When mode owner changes to default mode, handle pending requests\n      if (currentMode === this.defaultMode && this.pendingRequests.size > 0) {\n        this.handlePendingRequestsOnDefaultMode(previousMode);\n      }\n    });\n    this.unsubscribers.push(unsubChanged);\n  }\n\n  /**\n   * Determine if a mode change request should be auto-accepted without authorization\n   */\n  private shouldAutoAcceptRequest(\n    desiredMode: string,\n    requestOwner: string,\n    currentModeOwner: string | undefined,\n    desiredModeOwner: string | undefined,\n  ): boolean {\n    // Owner returning to default mode\n    if (desiredMode === this.defaultMode && requestOwner === currentModeOwner) {\n      return true;\n    }\n\n    // Owner switching between their own modes\n    if (requestOwner === currentModeOwner) {\n      return true;\n    }\n\n    // No ownership conflicts exist\n    if (!(currentModeOwner || desiredModeOwner)) {\n      return true;\n    }\n\n    // Entering an owned mode from default mode\n    if (this.mode === this.defaultMode && requestOwner === desiredModeOwner) {\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Handle mode change request logic\n   */\n  private handleModeChangeRequest(\n    desiredMode: string,\n    requestOwner: string,\n  ): void {\n    const currentModeOwner = this.modeOwners.get(this.mode);\n    const desiredModeOwner = this.modeOwners.get(desiredMode);\n\n    // Check if this request should be auto-accepted\n    if (\n      this.shouldAutoAcceptRequest(\n        desiredMode,\n        requestOwner,\n        currentModeOwner,\n        desiredModeOwner,\n      )\n    ) {\n      this.setMode(desiredMode);\n\n      // Store the desired mode's owner unless it's default\n      if (desiredMode !== this.defaultMode && !desiredModeOwner) {\n        this.modeOwners.set(desiredMode, requestOwner);\n      }\n\n      // Clear requester's pending request since mode changed successfully\n      this.pendingRequests.delete(requestOwner);\n      return;\n    }\n\n    // Otherwise, send authorization request\n    const authId = uuid();\n\n    this.pendingRequests.set(requestOwner, {\n      authId,\n      desiredMode,\n      currentMode: this.mode,\n      requestOwner,\n    });\n\n    this.bus.emit(MapModeEvents.changeAuthorization, {\n      authId,\n      desiredMode,\n      currentMode: this.mode,\n      id: this.id,\n    });\n  }\n\n  /**\n   * Handle authorization decision\n   *\n   * Processes approval/rejection decisions from mode owners. Only the current mode's owner\n   * can make authorization decisions. If a decision comes from a non-owner, a warning is\n   * logged and the decision is ignored to prevent unauthorized mode changes.\n   *\n   * @param payload - The authorization decision containing authId, approved status, and owner\n   */\n  private handleAuthorizationDecision(payload: {\n    approved: boolean;\n    authId: string;\n    owner: string;\n  }): void {\n    const { approved, authId, owner: decisionOwner } = payload;\n\n    // Verify decision is from current mode's owner\n    // Logs a warning if unauthorized component attempts to make decisions\n    const currentModeOwner = this.modeOwners.get(this.mode);\n    if (decisionOwner !== currentModeOwner) {\n      console.warn(\n        `[MapMode] Authorization decision from \"${decisionOwner}\" ignored - not the owner of mode \"${this.mode}\" (owner: ${currentModeOwner || 'none'})`,\n      );\n      return;\n    }\n\n    // Find the request with matching authId\n    let matchingRequestOwner: string | null = null;\n    let matchingRequest: PendingRequest | null = null;\n\n    for (const [requestOwner, request] of this.pendingRequests.entries()) {\n      if (request.authId === authId) {\n        matchingRequestOwner = requestOwner;\n        matchingRequest = request;\n        break;\n      }\n    }\n\n    if (!(matchingRequest && matchingRequestOwner)) {\n      return;\n    }\n\n    if (approved) {\n      this.approveRequestAndRejectOthers(\n        matchingRequest,\n        authId,\n        decisionOwner,\n        '',\n        false,\n      );\n    } else {\n      this.pendingRequests.delete(matchingRequestOwner);\n    }\n  }\n\n  /**\n   * Approve a request and reject all others\n   */\n  private approveRequestAndRejectOthers(\n    approvedRequest: PendingRequest,\n    excludeAuthId: string,\n    decisionOwner: string,\n    reason: string,\n    emitApproval: boolean,\n  ): void {\n    // Collect all other pending requests to emit rejections for\n    const requestsToReject: PendingRequest[] = [];\n    for (const request of this.pendingRequests.values()) {\n      if (request.authId !== excludeAuthId) {\n        requestsToReject.push(request);\n      }\n    }\n\n    // Clear all pending requests BEFORE changing mode\n    this.pendingRequests.clear();\n\n    // Change mode\n    this.setMode(approvedRequest.desiredMode);\n\n    // Store the new mode's owner (unless it's default mode)\n    if (approvedRequest.desiredMode !== this.defaultMode) {\n      this.modeOwners.set(\n        approvedRequest.desiredMode,\n        approvedRequest.requestOwner,\n      );\n    }\n\n    // Emit approval decision if requested\n    if (emitApproval) {\n      this.bus.emit(MapModeEvents.changeDecision, {\n        authId: approvedRequest.authId,\n        approved: true,\n        owner: decisionOwner,\n        reason,\n        id: this.id,\n      });\n    }\n\n    // Emit rejection events for all other pending requests\n    for (const request of requestsToReject) {\n      this.bus.emit(MapModeEvents.changeDecision, {\n        authId: request.authId,\n        approved: false,\n        owner: decisionOwner,\n        reason: 'Request auto-rejected because another request was approved',\n        id: this.id,\n      });\n    }\n  }\n\n  /**\n   * Handle pending requests when returning to default mode\n   */\n  private handlePendingRequestsOnDefaultMode(previousMode: string): void {\n    const firstEntry = Array.from(this.pendingRequests.values())[0];\n    if (!firstEntry) {\n      return;\n    }\n\n    const previousModeOwner = this.modeOwners.get(previousMode);\n\n    if (!previousModeOwner) {\n      return;\n    }\n\n    // If the first pending request is for default mode, reject all requests\n    if (firstEntry.desiredMode === this.defaultMode) {\n      const allRequests = Array.from(this.pendingRequests.values());\n      this.pendingRequests.clear();\n\n      for (const request of allRequests) {\n        this.bus.emit(MapModeEvents.changeDecision, {\n          authId: request.authId,\n          approved: false,\n          owner: previousModeOwner,\n          reason: 'Request rejected - already in requested mode',\n          id: this.id,\n        } satisfies ModeChangeDecisionPayload);\n      }\n    } else {\n      // Auto-accept the first pending request for a different mode\n      this.approveRequestAndRejectOthers(\n        firstEntry,\n        firstEntry.authId,\n        previousModeOwner,\n        'Auto-accepted when mode owner returned to default',\n        true,\n      );\n    }\n  }\n\n  /**\n   * Set mode and notify listeners\n   */\n  private setMode(newMode: string): void {\n    const previousMode = this.mode;\n    this.mode = newMode;\n\n    this.bus.emit(MapModeEvents.changed, {\n      previousMode,\n      currentMode: newMode,\n      id: this.id,\n    });\n\n    this.notify();\n  }\n\n  /**\n   * Clean up store resources\n   */\n  destroy(): void {\n    // Unsubscribe from all bus events\n    for (const unsubscribe of this.unsubscribers) {\n      unsubscribe();\n    }\n    this.unsubscribers.length = 0;\n\n    // Clear all state\n    this.modeOwners.clear();\n    this.pendingRequests.clear();\n    this.listeners.clear();\n  }\n}\n\n/**\n * Global store registry\n */\nconst storeRegistry = new Map<UniqueId, MapModeStore>();\n\n/**\n * Get or create a store for a given map instance\n */\nexport function getOrCreateStore(id: UniqueId): MapModeStore {\n  if (!storeRegistry.has(id)) {\n    storeRegistry.set(id, new MapModeStore(id));\n  }\n  // biome-ignore lint/style/noNonNullAssertion: Store guaranteed to exist after has() check above\n  return storeRegistry.get(id)!;\n}\n\n/**\n * Destroy and remove a store from the registry\n */\nexport function destroyStore(id: UniqueId): void {\n  const store = storeRegistry.get(id);\n  if (store) {\n    store.destroy();\n    storeRegistry.delete(id);\n  }\n}\n\n/**\n * Get a store by map ID (for testing/advanced use)\n */\nexport function getStore(id: UniqueId): MapModeStore | undefined {\n  return storeRegistry.get(id);\n}\n"]}

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

@@ -0,0 +1,83 @@
+import { Payload } from '@accelint/bus';
+import { UniqueId } from '@accelint/core';
+import { MapModeEvents } from './events.js';
+
+/**
+ * Payload emitted when the map mode has successfully changed.
+ */
+type ModeChangedPayload = {
+    /** The mode before the change */
+    previousMode: string;
+    /** The mode after the change */
+    currentMode: string;
+    /** The ID of the map this event is for */
+    id: UniqueId;
+};
+/**
+ * Payload for requesting a map mode change.
+ * This initiates the mode change flow.
+ */
+type ModeChangeRequestPayload = {
+    /** The mode being requested */
+    desiredMode: string;
+    /** The identifier of the component requesting the mode change */
+    owner: string;
+    /** The ID of the map this event is for */
+    id: UniqueId;
+};
+/**
+ * Payload emitted when a mode change requires authorization.
+ * This is sent to the current mode owner to approve or reject the request.
+ */
+type ModeChangeAuthorizationPayload = {
+    /** Unique identifier for this authorization request */
+    authId: string;
+    /** The mode being requested */
+    desiredMode: string;
+    /** The current active mode */
+    currentMode: string;
+    /** The ID of the map this event is for */
+    id: UniqueId;
+};
+/**
+ * Payload for an authorization decision from the current mode owner.
+ * This completes the authorization flow.
+ */
+type ModeChangeDecisionPayload = {
+    /** The authId from the corresponding authorization request */
+    authId: string;
+    /** Whether the mode change was approved */
+    approved: boolean;
+    /** The identifier of the component making the decision (must be current mode owner) */
+    owner: string;
+    /** Optional reason for rejection */
+    reason?: string;
+    /** The ID of the map this event is for */
+    id: UniqueId;
+};
+/**
+ * Event type for mode change notifications.
+ * Emitted when the map mode has successfully changed.
+ */
+type ModeChangedEvent = Payload<typeof MapModeEvents.changed, ModeChangedPayload>;
+/**
+ * Event type for mode change requests.
+ * Emitted when a component requests a mode change.
+ */
+type ModeChangeRequestEvent = Payload<typeof MapModeEvents.changeRequest, ModeChangeRequestPayload>;
+/**
+ * Event type for mode change authorization requests.
+ * Emitted when a mode change requires approval from the current mode owner.
+ */
+type ModeChangeAuthorizationEvent = Payload<typeof MapModeEvents.changeAuthorization, ModeChangeAuthorizationPayload>;
+/**
+ * Event type for authorization decisions.
+ * Emitted when the current mode owner approves or rejects a mode change request.
+ */
+type ModeChangeDecisionEvent = Payload<typeof MapModeEvents.changeDecision, ModeChangeDecisionPayload>;
+/**
+ * Union type of all map mode event types that can be emitted through the event bus.
+ */
+type MapModeEventType = ModeChangedEvent | ModeChangeRequestEvent | ModeChangeAuthorizationEvent | ModeChangeDecisionEvent;
+
+export type { MapModeEventType, ModeChangeAuthorizationEvent, ModeChangeAuthorizationPayload, ModeChangeDecisionEvent, ModeChangeDecisionPayload, ModeChangeRequestEvent, ModeChangeRequestPayload, ModeChangedEvent, ModeChangedPayload };

package/dist/map-mode/types.js

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"types.js"}

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

@@ -0,0 +1,54 @@
+import { UniqueId } from '@accelint/core';
+
+/**
+ * Return value for the useMapMode hook
+ */
+type UseMapModeReturn = {
+    /** The current active map mode */
+    mode: string;
+    /** Function to request a mode change with ownership */
+    requestModeChange: (desiredMode: string, requestOwner: string) => void;
+};
+/**
+ * Hook to access the map mode state and actions.
+ *
+ * This hook uses `useSyncExternalStore` to subscribe to the external `MapModeStore`,
+ * providing concurrent-safe mode state updates. The hybrid architecture separates:
+ * - Map instance identity (from `MapContext` or parameter)
+ * - Mode state management (from `MapModeStore` via `useSyncExternalStore`)
+ *
+ * @param id - Optional map instance ID. If not provided, will use the ID from `MapContext`.
+ * @returns The current map mode and requestModeChange function
+ * @throws Error if no `id` is provided and hook is used outside of `MapProvider`
+ * @throws Error if store doesn't exist for the given map ID
+ *
+ * @example
+ * ```tsx
+ * // Inside MapProvider (within BaseMap children) - uses context
+ * // Only Deck.gl layer components can be children
+ * function CustomDeckLayer() {
+ *   const { mode, requestModeChange } = useMapMode();
+ *
+ *   const handleClick = (info: PickingInfo) => {
+ *     requestModeChange('editing', 'custom-layer-id');
+ *   };
+ *
+ *   return <ScatterplotLayer onClick={handleClick} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Outside MapProvider - pass id directly
+ * function ExternalControl({ mapId }: { mapId: UniqueId }) {
+ *   const { mode, requestModeChange } = useMapMode(mapId);
+ *
+ *   return <button onClick={() => requestModeChange('default', 'external')}>
+ *     Reset to Default (current: {mode})
+ *   </button>;
+ * }
+ * ```
+ */
+declare function useMapMode(id?: UniqueId): UseMapModeReturn;
+
+export { type UseMapModeReturn, useMapMode };

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

@@ -0,0 +1,31 @@
+import { useContext, useSyncExternalStore, useMemo } from 'react';
+import { MapContext } from '../deckgl/base-map/provider.js';
+import { getStore } from './store.js';
+
+function useMapMode(id) {
+  const contextId = useContext(MapContext);
+  const actualId = id ?? contextId;
+  if (!actualId) {
+    throw new Error(
+      "useMapMode requires either an id parameter or to be used within a MapProvider"
+    );
+  }
+  const store = getStore(actualId);
+  if (!store) {
+    throw new Error(
+      `MapModeStore not found for map instance: ${actualId}. Ensure a store has been created for this map instance (e.g., via MapProvider or getOrCreateStore).`
+    );
+  }
+  const mode = useSyncExternalStore(store.subscribe, store.getSnapshot);
+  return useMemo(
+    () => ({
+      mode,
+      requestModeChange: store.requestModeChange
+    }),
+    [mode, store]
+  );
+}
+
+export { useMapMode };
+//# sourceMappingURL=use-map-mode.js.map
+//# sourceMappingURL=use-map-mode.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/map-mode/use-map-mode.ts"],"names":[],"mappings":";;;;AAmEO,SAAS,WAAW,EAAA,EAAiC;AAC1D,EAAA,MAAM,SAAA,GAAY,WAAW,UAAU,CAAA;AACvC,EAAA,MAAM,WAAW,EAAA,IAAM,SAAA;AAEvB,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AAGA,EAAA,MAAM,KAAA,GAAQ,SAAS,QAAQ,CAAA;AAE/B,EAAA,IAAI,CAAC,KAAA,EAAO;AACV,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,4CAA4C,QAAQ,CAAA,oGAAA;AAAA,KACtD;AAAA,EACF;AAGA,EAAA,MAAM,IAAA,GAAO,oBAAA,CAAqB,KAAA,CAAM,SAAA,EAAW,MAAM,WAAW,CAAA;AAGpE,EAAA,OAAO,OAAA;AAAA,IACL,OAAO;AAAA,MACL,IAAA;AAAA,MACA,mBAAmB,KAAA,CAAM;AAAA,KAC3B,CAAA;AAAA,IACA,CAAC,MAAM,KAAK;AAAA,GACd;AACF","file":"use-map-mode.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\nimport { useContext, useMemo, useSyncExternalStore } from 'react';\nimport { MapContext } from '../deckgl/base-map/provider';\nimport { getStore } from './store';\nimport type { UniqueId } from '@accelint/core';\n\n/**\n * Return value for the useMapMode hook\n */\nexport type UseMapModeReturn = {\n  /** The current active map mode */\n  mode: string;\n  /** Function to request a mode change with ownership */\n  requestModeChange: (desiredMode: string, requestOwner: string) => void;\n};\n\n/**\n * Hook to access the map mode state and actions.\n *\n * This hook uses `useSyncExternalStore` to subscribe to the external `MapModeStore`,\n * providing concurrent-safe mode state updates. The hybrid architecture separates:\n * - Map instance identity (from `MapContext` or parameter)\n * - Mode state management (from `MapModeStore` via `useSyncExternalStore`)\n *\n * @param id - Optional map instance ID. If not provided, will use the ID from `MapContext`.\n * @returns The current map mode and requestModeChange function\n * @throws Error if no `id` is provided and hook is used outside of `MapProvider`\n * @throws Error if store doesn't exist for the given map ID\n *\n * @example\n * ```tsx\n * // Inside MapProvider (within BaseMap children) - uses context\n * // Only Deck.gl layer components can be children\n * function CustomDeckLayer() {\n *   const { mode, requestModeChange } = useMapMode();\n *\n *   const handleClick = (info: PickingInfo) => {\n *     requestModeChange('editing', 'custom-layer-id');\n *   };\n *\n *   return <ScatterplotLayer onClick={handleClick} />;\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Outside MapProvider - pass id directly\n * function ExternalControl({ mapId }: { mapId: UniqueId }) {\n *   const { mode, requestModeChange } = useMapMode(mapId);\n *\n *   return <button onClick={() => requestModeChange('default', 'external')}>\n *     Reset to Default (current: {mode})\n *   </button>;\n * }\n * ```\n */\nexport function useMapMode(id?: UniqueId): UseMapModeReturn {\n  const contextId = useContext(MapContext);\n  const actualId = id ?? contextId;\n\n  if (!actualId) {\n    throw new Error(\n      'useMapMode requires either an id parameter or to be used within a MapProvider',\n    );\n  }\n\n  // Get the store for this map instance\n  const store = getStore(actualId);\n\n  if (!store) {\n    throw new Error(\n      `MapModeStore not found for map instance: ${actualId}. Ensure a store has been created for this map instance (e.g., via MapProvider or getOrCreateStore).`,\n    );\n  }\n\n  // Subscribe to store using useSyncExternalStore\n  const mode = useSyncExternalStore(store.subscribe, store.getSnapshot);\n\n  // Memoize the return value to prevent unnecessary re-renders\n  return useMemo(\n    () => ({\n      mode,\n      requestModeChange: store.requestModeChange,\n    }),\n    [mode, store],\n  );\n}\n"]}

package/dist/maplibre/hooks/use-maplibre.d.ts

@@ -1,5 +1,39 @@
 import { IControl, MapOptions, Map } from 'maplibre-gl';
 
+/**
+ * Hook to integrate a MapLibre GL map with a Deck.gl instance.
+ *
+ * This hook manages the lifecycle of a MapLibre map, including initialization,
+ * style updates, and cleanup. It ensures the Deck.gl control is properly added
+ * to the map and handles cleanup when the component unmounts.
+ *
+ * @param deck - The Deck.gl IControl instance to add to the map
+ * @param styleUrl - The MapLibre style URL to use for the map
+ * @param options - MapLibre map options (container, center, zoom, etc.)
+ * @returns The MapLibre map instance, or null if not yet initialized
+ *
+ * @example
+ * ```tsx
+ * function MapComponent() {
+ *   const deckglInstance = useDeckgl();
+ *   const container = useId();
+ *
+ *   const mapOptions = useMemo(() => ({
+ *     container,
+ *     center: [-122.4, 37.8],
+ *     zoom: 12,
+ *   }), [container]);
+ *
+ *   useMapLibre(
+ *     deckglInstance as IControl,
+ *     'https://tiles.example.com/style.json',
+ *     mapOptions
+ *   );
+ *
+ *   return <div id={container} />;
+ * }
+ * ```
+ */
 declare function useMapLibre(deck: IControl | null, styleUrl: string, options: MapOptions): Map | null;
 
 export { useMapLibre };

package/dist/maplibre/hooks/use-maplibre.js

@@ -3,11 +3,12 @@ import { useRef, useEffect } from 'react';
 
 function useMapLibre(deck, styleUrl, options) {
   const mapRef = useRef(null);
+  const optionsRef = useRef(options);
   const styleRef = useRef(styleUrl);
   useEffect(() => {
     if (deck && !mapRef.current) {
       mapRef.current = new Map({
-        ...options,
+        ...optionsRef.current,
         style: styleRef.current
       });
       mapRef.current.once("style.load", () => {
@@ -22,7 +23,7 @@ function useMapLibre(deck, styleUrl, options) {
         }
       };
     }
-  }, [deck, options]);
+  }, [deck]);
   useEffect(() => {
     if (mapRef.current) {
       mapRef.current.setStyle(styleUrl);

package/dist/maplibre/hooks/use-maplibre.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/maplibre/hooks/use-maplibre.ts"],"names":["MapLibre"],"mappings":";;;AAeO,SAAS,WAAA,CACd,IAAA,EACA,QAAA,EACA,OAAA,EACA;AACA,EAAA,MAAM,MAAA,GAAS,OAAwB,IAAI,CAAA;AAE3C,EAAA,MAAM,QAAA,GAAW,OAAO,QAAQ,CAAA;AAGhC,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,IAAQ,CAAC,MAAA,CAAO,OAAA,EAAS;AAC3B,MAAA,MAAA,CAAO,OAAA,GAAU,IAAIA,GAAA,CAAS;AAAA,QAC5B,GAAG,OAAA;AAAA,QACH,OAAO,QAAA,CAAS;AAAA,OACjB,CAAA;AAED,MAAA,MAAA,CAAO,OAAA,CAAQ,IAAA,CAAK,YAAA,EAAc,MAAM;AACtC,QAAA,MAAA,CAAO,OAAA,EAAS,aAAA,CAAc,EAAE,IAAA,EAAM,YAAY,CAAA;AAClD,QAAA,MAAA,CAAO,OAAA,EAAS,WAAW,IAAI,CAAA;AAAA,MACjC,CAAC,CAAA;AAED,MAAA,OAAO,MAAM;AACX,QAAA,IAAI,OAAO,OAAA,EAAS;AAClB,UAAA,MAAA,CAAO,OAAA,CAAQ,cAAc,IAAI,CAAA;AACjC,UAAA,MAAA,CAAO,QAAQ,MAAA,EAAO;AACtB,UAAA,MAAA,CAAO,OAAA,GAAU,IAAA;AAAA,QACnB;AAAA,MACF,CAAA;AAAA,IACF;AAAA,EACF,CAAA,EAAG,CAAC,IAAA,EAAM,OAAO,CAAC,CAAA;AAGlB,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,OAAO,OAAA,EAAS;AAClB,MAAA,MAAA,CAAO,OAAA,CAAQ,SAAS,QAAQ,CAAA;AAAA,IAClC;AAAA,EACF,CAAA,EAAG,CAAC,QAAQ,CAAC,CAAA;AAEb,EAAA,OAAO,MAAA,CAAO,OAAA;AAChB","file":"use-maplibre.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\nimport { type IControl, Map as MapLibre, type MapOptions } from 'maplibre-gl';\nimport { useEffect, useRef } from 'react';\n\nexport function useMapLibre(\n  deck: IControl | null,\n  styleUrl: string,\n  options: MapOptions,\n) {\n  const mapRef = useRef<MapLibre | null>(null);\n  // using a ref in the initial setup so that it doesn't cause a re-run of the effect on change\n  const styleRef = useRef(styleUrl);\n\n  // Initialize MapLibre instance once\n  useEffect(() => {\n    if (deck && !mapRef.current) {\n      mapRef.current = new MapLibre({\n        ...options,\n        style: styleRef.current,\n      });\n\n      mapRef.current.once('style.load', () => {\n        mapRef.current?.setProjection({ type: 'mercator' });\n        mapRef.current?.addControl(deck);\n      });\n\n      return () => {\n        if (mapRef.current) {\n          mapRef.current.removeControl(deck);\n          mapRef.current.remove();\n          mapRef.current = null;\n        }\n      };\n    }\n  }, [deck, options]);\n\n  // Update style when it changes\n  useEffect(() => {\n    if (mapRef.current) {\n      mapRef.current.setStyle(styleUrl);\n    }\n  }, [styleUrl]);\n\n  return mapRef.current;\n}\n"]}
+{"version":3,"sources":["../../../src/maplibre/hooks/use-maplibre.ts"],"names":["MapLibre"],"mappings":";;;AAiDO,SAAS,WAAA,CACd,IAAA,EACA,QAAA,EACA,OAAA,EACA;AACA,EAAA,MAAM,MAAA,GAAS,OAAwB,IAAI,CAAA;AAG3C,EAAA,MAAM,UAAA,GAAa,OAAO,OAAO,CAAA;AAEjC,EAAA,MAAM,QAAA,GAAW,OAAO,QAAQ,CAAA;AAGhC,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,IAAA,IAAQ,CAAC,MAAA,CAAO,OAAA,EAAS;AAC3B,MAAA,MAAA,CAAO,OAAA,GAAU,IAAIA,GAAA,CAAS;AAAA,QAC5B,GAAG,UAAA,CAAW,OAAA;AAAA,QACd,OAAO,QAAA,CAAS;AAAA,OACjB,CAAA;AAED,MAAA,MAAA,CAAO,OAAA,CAAQ,IAAA,CAAK,YAAA,EAAc,MAAM;AACtC,QAAA,MAAA,CAAO,OAAA,EAAS,aAAA,CAAc,EAAE,IAAA,EAAM,YAAY,CAAA;AAClD,QAAA,MAAA,CAAO,OAAA,EAAS,WAAW,IAAI,CAAA;AAAA,MACjC,CAAC,CAAA;AAED,MAAA,OAAO,MAAM;AACX,QAAA,IAAI,OAAO,OAAA,EAAS;AAClB,UAAA,MAAA,CAAO,OAAA,CAAQ,cAAc,IAAI,CAAA;AACjC,UAAA,MAAA,CAAO,QAAQ,MAAA,EAAO;AACtB,UAAA,MAAA,CAAO,OAAA,GAAU,IAAA;AAAA,QACnB;AAAA,MACF,CAAA;AAAA,IACF;AAAA,EACF,CAAA,EAAG,CAAC,IAAI,CAAC,CAAA;AAGT,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,IAAI,OAAO,OAAA,EAAS;AAClB,MAAA,MAAA,CAAO,OAAA,CAAQ,SAAS,QAAQ,CAAA;AAAA,IAClC;AAAA,EACF,CAAA,EAAG,CAAC,QAAQ,CAAC,CAAA;AAEb,EAAA,OAAO,MAAA,CAAO,OAAA;AAChB","file":"use-maplibre.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\nimport { type IControl, Map as MapLibre, type MapOptions } from 'maplibre-gl';\nimport { useEffect, useRef } from 'react';\n\n/**\n * Hook to integrate a MapLibre GL map with a Deck.gl instance.\n *\n * This hook manages the lifecycle of a MapLibre map, including initialization,\n * style updates, and cleanup. It ensures the Deck.gl control is properly added\n * to the map and handles cleanup when the component unmounts.\n *\n * @param deck - The Deck.gl IControl instance to add to the map\n * @param styleUrl - The MapLibre style URL to use for the map\n * @param options - MapLibre map options (container, center, zoom, etc.)\n * @returns The MapLibre map instance, or null if not yet initialized\n *\n * @example\n * ```tsx\n * function MapComponent() {\n *   const deckglInstance = useDeckgl();\n *   const container = useId();\n *\n *   const mapOptions = useMemo(() => ({\n *     container,\n *     center: [-122.4, 37.8],\n *     zoom: 12,\n *   }), [container]);\n *\n *   useMapLibre(\n *     deckglInstance as IControl,\n *     'https://tiles.example.com/style.json',\n *     mapOptions\n *   );\n *\n *   return <div id={container} />;\n * }\n * ```\n */\nexport function useMapLibre(\n  deck: IControl | null,\n  styleUrl: string,\n  options: MapOptions,\n) {\n  const mapRef = useRef<MapLibre | null>(null);\n  // Using a ref for options to avoid re-creating the map when options object reference changes\n  // The map is only created once on mount, options changes after that are ignored\n  const optionsRef = useRef(options);\n  // using a ref in the initial setup so that it doesn't cause a re-run of the effect on change\n  const styleRef = useRef(styleUrl);\n\n  // Initialize MapLibre instance once\n  useEffect(() => {\n    if (deck && !mapRef.current) {\n      mapRef.current = new MapLibre({\n        ...optionsRef.current,\n        style: styleRef.current,\n      });\n\n      mapRef.current.once('style.load', () => {\n        mapRef.current?.setProjection({ type: 'mercator' });\n        mapRef.current?.addControl(deck);\n      });\n\n      return () => {\n        if (mapRef.current) {\n          mapRef.current.removeControl(deck);\n          mapRef.current.remove();\n          mapRef.current = null;\n        }\n      };\n    }\n  }, [deck]);\n\n  // Update style when it changes\n  useEffect(() => {\n    if (mapRef.current) {\n      mapRef.current.setStyle(styleUrl);\n    }\n  }, [styleUrl]);\n\n  return mapRef.current;\n}\n"]}