@swisper.ai/web-map 0.0.2

package/dist/user-location-pin.d.ts

@@ -0,0 +1,8 @@
+export interface UserLocationPinProps {
+    className?: string;
+    /** Tooltip and accessible name; pass a translated string. */
+    label?: string;
+}
+/** Map marker for the user's own position: a blue dot with a white ring. */
+export declare function UserLocationPin({ className, label }: UserLocationPinProps): import('react').JSX.Element;
+//# sourceMappingURL=user-location-pin.d.ts.map

package/dist/user-location-pin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-location-pin.d.ts","sourceRoot":"","sources":["../src/user-location-pin.tsx"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,EAAE,SAAS,EAAE,KAAqB,EAAE,EAAE,oBAAoB,+BAiBzF"}

package/dist/utils/get-bounds-from-points.d.ts

@@ -0,0 +1,10 @@
+export type MapLngLat = [number, number];
+export type MapBounds = [MapLngLat, MapLngLat];
+/**
+ * Computes a southwest/northeast bounding box from lng/lat points.
+ * Returns null when there are no points.
+ */
+export declare function getBoundsFromPoints(points: MapLngLat[]): MapBounds | null;
+export declare function getBoundsCentroid(bounds: MapBounds): MapLngLat;
+export declare function isDegenerateBounds(bounds: MapBounds): boolean;
+//# sourceMappingURL=get-bounds-from-points.d.ts.map

package/dist/utils/get-bounds-from-points.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-bounds-from-points.d.ts","sourceRoot":"","sources":["../../src/utils/get-bounds-from-points.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACzC,MAAM,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,GAAG,IAAI,CAqBzE;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAG9D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAG7D"}

package/dist/worker/maplibre-worker-source.d.ts

@@ -0,0 +1,2 @@
+export { default } from 'virtual:maplibre-worker-source';
+//# sourceMappingURL=maplibre-worker-source.d.ts.map

package/dist/worker/maplibre-worker-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maplibre-worker-source.d.ts","sourceRoot":"","sources":["../../src/worker/maplibre-worker-source.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,gCAAgC,CAAC"}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@swisper.ai/web-map",
+  "version": "0.0.2",
+  "description": "Interactive MapLibre maps with selectable markers for Swisper web apps",
+  "keywords": [
+    "react",
+    "map",
+    "maplibre",
+    "design-system"
+  ],
+  "license": "Apache-2.0",
+  "author": "Fintama AG",
+  "homepage": "https://fintama.github.io/fintama/",
+  "type": "module",
+  "main": "./dist/index.es.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "source": "./src/index.ts",
+  "style": "./dist/index.css",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "style": "./dist/index.css",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.es.js"
+    },
+    "./index.css": {
+      "style": "./dist/index.css",
+      "import": "./dist/index.css",
+      "require": "./dist/index.css"
+    },
+    "./tailwind.css": {
+      "style": "./tailwind.css",
+      "import": "./tailwind.css",
+      "require": "./tailwind.css"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "tailwind.css"
+  ],
+  "dependencies": {
+    "@swisper.ai/icons": "0.0.2",
+    "@swisper.ai/tailwind-config": "0.0.2",
+    "@swisper.ai/ui": "0.0.2",
+    "@swisper.ai/web-core": "0.0.2",
+    "@vis.gl/react-maplibre": "^8.1.3",
+    "maplibre-gl": "^6.4.1"
+  },
+  "devDependencies": {
+    "@fintama/vite-config": "0.1.1",
+    "@fintama/vitest-config": "0.1.1",
+    "@storybook/react-vite": "10.6.0",
+    "@swisper.ai/int-eslint-config": "0.0.1",
+    "@swisper.ai/int-typescript-config": "0.0.1",
+    "@tailwindcss/cli": "4.3.3",
+    "@tailwindcss/vite": "4.3.3",
+    "@testing-library/dom": "10.4.1",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "24.19.0",
+    "@types/react": "18.3.31",
+    "@types/react-dom": "18.3.7",
+    "@typescript/typescript6": "6.0.2",
+    "concurrently": "^9.1.2",
+    "eslint": "10.9.1",
+    "jsdom": "30.1.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "rimraf": "^6.0.1",
+    "rollup-plugin-visualizer": "7.1.1",
+    "storybook": "10.6.0",
+    "tailwindcss": "4.3.3",
+    "typescript": "7.0.2",
+    "vite": "8.3.1",
+    "vite-plugin-dts": "5.1.1",
+    "vitest": "4.1.11"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run clean && pnpm run build:ts && pnpm run build:css",
+    "analyze": "ANALYZE=true vite build --mode production",
+    "build:ts": "vite build --mode production",
+    "build:css": "tailwindcss -i ./src/index.css -o ./dist/index.css --minify",
+    "clean": "rimraf dist",
+    "dev": "concurrently \"pnpm run dev:css\" \"pnpm run dev:ts\"",
+    "lint": "eslint . --max-warnings=0",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "dev:ts": "vite build --mode development --watch",
+    "dev:css": "tailwindcss -i ./src/index.css -o ./dist/index.css --watch"
+  }
+}

package/src/__storybook__/fixtures.ts

@@ -0,0 +1,19 @@
+import type { MapLngLat } from '../utils/get-bounds-from-points';
+
+export interface StoryPlace {
+  id: string;
+  label: string;
+  value: number;
+  lngLat: MapLngLat;
+}
+
+/** A few places around central Zurich, shared by the map stories. */
+export const PLACES: StoryPlace[] = [
+  { id: 'roma', label: 'Roma Pizza', value: 4.5, lngLat: [8.5417, 47.3769] },
+  { id: 'kaiser', label: 'Kaiser Grill', value: 4.2, lngLat: [8.5305, 47.3717] },
+  { id: 'lago', label: 'Lago Café', value: 4.8, lngLat: [8.5481, 47.3664] },
+];
+
+export const PLACE_POINTS: MapLngLat[] = PLACES.map((place) => place.lngLat);
+
+export const USER_LOCATION = { longitude: 8.5391, latitude: 47.3723 };

package/src/__tests__/load-map-lib.spec.ts

@@ -0,0 +1,57 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+/**
+ * maplibre-gl v6 cannot find its own worker once a consumer bundles it, so
+ * `loadMapLib` hands it one built from the source this package ships. That source
+ * is a build-time virtual module; vitest.config.ts aliases it to a one-line stub.
+ */
+
+vi.unmock('@/load-map-lib');
+
+const setWorkerUrl = vi.fn();
+
+vi.mock('maplibre-gl', () => ({ setWorkerUrl }));
+
+/** jsdom's Blob has no `text()`; its FileReader is the way in. */
+function readBlob(blob: Blob): Promise<string> {
+  return new Promise((resolve) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as string);
+    reader.readAsText(blob);
+  });
+}
+
+describe('loadMapLib', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    setWorkerUrl.mockClear();
+    URL.createObjectURL = vi.fn(() => 'blob:http://localhost/maplibre-worker');
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  test('points maplibre at a blob URL of the shipped worker source', async () => {
+    const { loadMapLib } = await import('@/load-map-lib');
+
+    const lib = await loadMapLib();
+
+    expect(lib.setWorkerUrl).toBe(setWorkerUrl);
+    expect(setWorkerUrl).toHaveBeenCalledExactlyOnceWith('blob:http://localhost/maplibre-worker');
+    const [blob] = vi.mocked(URL.createObjectURL).mock.calls[0] as [Blob];
+    expect(blob.type).toBe('text/javascript');
+    expect(await readBlob(blob)).toBe('self.onmessage = () => {};');
+  });
+
+  test('configures the worker once, however many maps ask', async () => {
+    const { loadMapLib } = await import('@/load-map-lib');
+
+    const [first, second] = await Promise.all([loadMapLib(), loadMapLib()]);
+    await loadMapLib();
+
+    expect(first).toBe(second);
+    expect(setWorkerUrl).toHaveBeenCalledTimes(1);
+    expect(URL.createObjectURL).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/map-marker.spec.tsx

@@ -0,0 +1,153 @@
+import { cleanup, fireEvent, render, screen } from '@testing-library/react';
+import { forwardRef, type ReactNode } from 'react';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+
+import { useMapView } from '../map-context';
+import { MapMarker, type MapMarkerState } from '../map-marker';
+import { MapView, type MapViewProps } from '../map-view';
+
+/**
+ * `MapMarker` is where the map's callbacks meet the DOM: selection, hover and
+ * the click that must not fall through to the map. The maplibre canvas is out
+ * of reach in jsdom, so `Map` and `Marker` are stood in by plain elements.
+ */
+
+/** The `originalEvent` the Marker stub hands to `onClick`, as maplibre would. */
+const originalEvent = { stopPropagation: vi.fn() };
+
+vi.mock('@vis.gl/react-maplibre', () => ({
+  Map: forwardRef<unknown, { children?: ReactNode }>(function MapStub({ children }, _ref) {
+    return <div>{children}</div>;
+  }),
+  Marker: ({
+    children,
+    onClick,
+  }: {
+    children?: ReactNode;
+    onClick?: (e: { originalEvent: typeof originalEvent }) => void;
+  }) => (
+    // Stands in for maplibre's marker element, which owns the click in production.
+    // eslint-disable-next-line jsx-a11y/no-static-element-interactions
+    <div onClick={() => onClick?.({ originalEvent })}>{children}</div>
+  ),
+}));
+
+/** A map with nothing selected and spy callbacks. */
+function viewProps(overrides: Partial<MapViewProps<number>> = {}): MapViewProps<number> {
+  return {
+    testId: 'map',
+    ariaLabel: 'Map',
+    fitPoints: [[8.54, 47.37]],
+    onSelect: vi.fn(),
+    onHover: vi.fn(),
+    ...overrides,
+  };
+}
+
+function renderMarkers(props: MapViewProps<number>, children?: ReactNode) {
+  return render(
+    <MapView {...props}>
+      {children ?? (
+        <>
+          <MapMarker id={0} longitude={8.54} latitude={47.37} label="Zurich">
+            <span>pin</span>
+          </MapMarker>
+          <MapMarker id={1} longitude={7.44} latitude={46.95} label="Bern">
+            <span>pin</span>
+          </MapMarker>
+        </>
+      )}
+    </MapView>,
+  );
+}
+
+beforeEach(() => {
+  originalEvent.stopPropagation.mockClear();
+  // React logs the boundary-less throw itself; the guard test expects it.
+  vi.spyOn(console, 'error').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('callbacks', () => {
+  test('clicking a marker selects its id', () => {
+    const props = viewProps();
+    renderMarkers(props);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Bern' }));
+
+    expect(props.onSelect).toHaveBeenCalledWith(1);
+  });
+
+  test('the click does not reach the map', () => {
+    // The map's own click handler deselects; a marker click that bubbles up
+    // would select and immediately deselect.
+    renderMarkers(viewProps());
+
+    fireEvent.click(screen.getByRole('button', { name: 'Zurich' }));
+
+    expect(originalEvent.stopPropagation).toHaveBeenCalled();
+  });
+
+  test('hovering reports the id, leaving reports null', () => {
+    const props = viewProps();
+    renderMarkers(props);
+    const zurich = screen.getByRole('button', { name: 'Zurich' });
+
+    fireEvent.mouseEnter(zurich);
+    fireEvent.mouseLeave(zurich);
+
+    expect(props.onHover).toHaveBeenNthCalledWith(1, 0);
+    expect(props.onHover).toHaveBeenNthCalledWith(2, null);
+  });
+});
+
+describe('marker state', () => {
+  test('only the selected marker is pressed', () => {
+    renderMarkers(viewProps({ selectedId: 1 }));
+
+    expect(screen.getByRole('button', { name: 'Bern' }).getAttribute('aria-pressed')).toBe('true');
+    expect(screen.getByRole('button', { name: 'Zurich' }).getAttribute('aria-pressed')).toBe(
+      'false',
+    );
+  });
+
+  test('a render-function child receives the selection and hover state', () => {
+    const seen: Record<string, MapMarkerState> = {};
+
+    renderMarkers(
+      viewProps({ selectedId: 0, hoveredId: 1 }),
+      <>
+        <MapMarker id={0} longitude={8.54} latitude={47.37} label="Zurich">
+          {(state) => {
+            seen.zurich = state;
+            return <span>pin</span>;
+          }}
+        </MapMarker>
+        <MapMarker id={1} longitude={7.44} latitude={46.95} label="Bern">
+          {(state) => {
+            seen.bern = state;
+            return <span>pin</span>;
+          }}
+        </MapMarker>
+      </>,
+    );
+
+    expect(seen.zurich).toEqual({ isSelected: true, isHovered: false });
+    expect(seen.bern).toEqual({ isSelected: false, isHovered: true });
+  });
+});
+
+describe('useMapView outside a MapView', () => {
+  test('throws a message naming the missing root', () => {
+    function Probe() {
+      useMapView();
+      return null;
+    }
+
+    expect(() => render(<Probe />)).toThrow('useMapView must be used within a MapView component');
+  });
+});

package/src/__tests__/map-pin.spec.tsx

@@ -0,0 +1,82 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import { MapViewContext, type MapViewContextValue } from '../map-context';
+import { MapMarker } from '../map-marker';
+import { MapPin } from '../map-pin';
+
+vi.mock('@vis.gl/react-maplibre', () => ({
+  Marker: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
+}));
+
+/** A map root with nothing selected or hovered. */
+function mapContext(overrides: Partial<MapViewContextValue> = {}): MapViewContextValue {
+  return {
+    mapRef: { current: null },
+    selectedId: null,
+    hoveredId: null,
+    flyToSelected: false,
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('content', () => {
+  test('shows both the value and the label', () => {
+    render(<MapPin label="Roma Pizza" value={4.5} />);
+
+    expect(screen.getByText('4.5')).not.toBeNull();
+    expect(screen.getByText('Roma Pizza')).not.toBeNull();
+  });
+
+  test('treats an empty value as none', () => {
+    // A place without a rating comes through as '' as well as null; neither
+    // should leave an empty value slot beside the name.
+    const { container } = render(<MapPin label="Bluebird Cafe" value="" />);
+
+    expect(container.textContent).toBe('Bluebird Cafe');
+  });
+});
+
+describe('state', () => {
+  test('follows the enclosing marker', () => {
+    render(
+      <MapViewContext.Provider value={mapContext({ selectedId: 'a', hoveredId: 'b' })}>
+        <MapMarker id="a" longitude={0} latitude={0} label="A">
+          <MapPin label="A" data-testid="pin-a" />
+        </MapMarker>
+        <MapMarker id="b" longitude={0} latitude={0} label="B">
+          <MapPin label="B" data-testid="pin-b" />
+        </MapMarker>
+      </MapViewContext.Provider>,
+    );
+
+    expect(screen.getByTestId('pin-a').dataset.selected).toBe('true');
+    expect(screen.getByTestId('pin-a').dataset.hovered).toBeUndefined();
+    expect(screen.getByTestId('pin-b').dataset.hovered).toBe('true');
+  });
+
+  test('explicit props win over the marker', () => {
+    // Lets a caller pin the look (e.g. in a legend) regardless of selection.
+    render(
+      <MapViewContext.Provider value={mapContext({ selectedId: 'a' })}>
+        <MapMarker id="a" longitude={0} latitude={0} label="A">
+          <MapPin label="A" isSelected={false} data-testid="pin-a" />
+        </MapMarker>
+      </MapViewContext.Provider>,
+    );
+
+    expect(screen.getByTestId('pin-a').dataset.selected).toBeUndefined();
+  });
+
+  test('works outside a marker', () => {
+    render(<MapPin label="Standalone" isHovered />);
+
+    expect(screen.getByTestId('map-pin').dataset.hovered).toBe('true');
+  });
+});

package/src/__tests__/map-user-location.spec.tsx

@@ -0,0 +1,48 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import { TooltipProvider } from '@swisper.ai/ui';
+
+import { MapUserLocation } from '../map-user-location';
+
+vi.mock('@vis.gl/react-maplibre', () => ({
+  Marker: ({ children }: { children?: ReactNode }) => <div>{children}</div>,
+}));
+
+const ZURICH = { longitude: 8.54, latitude: 47.37 };
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('MapUserLocation', () => {
+  test('renders nothing while the position is unknown', () => {
+    // Geolocation resolves late or is denied; the map must not drop a dot at 0,0.
+    const { container } = render(<MapUserLocation coordinates={null} />);
+
+    expect(container.innerHTML).toBe('');
+  });
+
+  test('shows the default dot once the position is known', () => {
+    render(
+      <TooltipProvider>
+        <MapUserLocation coordinates={ZURICH} />
+      </TooltipProvider>,
+    );
+
+    expect(screen.getByRole('img')).not.toBeNull();
+  });
+
+  test('renders a custom marker in place of the dot', () => {
+    render(
+      <MapUserLocation coordinates={ZURICH}>
+        <span>you</span>
+      </MapUserLocation>,
+    );
+
+    expect(screen.getByText('you')).not.toBeNull();
+    expect(screen.queryByRole('img')).toBeNull();
+  });
+});

package/src/__tests__/maplibre-worker-source.stub.ts

@@ -0,0 +1,2 @@
+// Stands in for `virtual:maplibre-worker-source`, which only the build plugin can serve.
+export default 'self.onmessage = () => {};';

package/src/__tests__/setup.ts

@@ -0,0 +1,13 @@
+import { configure } from '@testing-library/react';
+import { vi } from 'vitest';
+
+// Under a parallel `turbo run test` a render can land seconds after the event that caused it,
+// past the 1s default. A wait that holds returns at once, so only a real failure takes longer.
+configure({ asyncUtilTimeout: 5_000 });
+
+// Every `BaseMap` render asks for maplibre. jsdom can neither run it nor create
+// the worker's blob URL, and the specs stub `Map` anyway, so hand them a promise
+// that never settles. `load-map-lib.spec.ts` unmocks it to test the real one.
+vi.mock('@/load-map-lib', () => ({
+  loadMapLib: () => new Promise(() => {}),
+}));

package/src/base-map.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "../../int-eslint-config/schemas/component.schema.json",
+  "component": "base-map",
+  "purpose": "The bare MapLibre map surface with loading and error states, framing and style URL, but no selection context.",
+  "useWhen": [
+    "Drawing custom sources, layers or plain markers that need no shared selection or hover",
+    "Building a new map component that manages its own view state through mapRef",
+    "Showing a map at a fixed centre and zoom, or framing explicit bounds"
+  ],
+  "avoidWhen": [
+    "Showing selectable, hoverable places — use web-map/map-view with web-map/map-marker instead",
+    "Framing a list of points — web-map/map-view computes the bounds and initial centre from fitPoints for you"
+  ],
+  "uxPrinciples": [
+    "Keep the map neutral while it loads or fails: tiles are hidden instead of half-rendered",
+    "An error replaces the map rather than overlaying an unusable one"
+  ],
+  "accessibility": {
+    "required": [
+      "Pass an ariaLabel that says what the map shows",
+      "Give any interactive marker you draw inside it its own accessible name",
+      "Provide the map's information in a non-map form as well when it matters to the task"
+    ],
+    "keyboard": [
+      "MapLibre's default keyboard handling applies when the map canvas has focus: arrow keys pan, + and - zoom",
+      "BaseMap adds no keyboard handling of its own"
+    ],
+    "aria": [
+      "The root is role=application with aria-label=ariaLabel",
+      "aria-invalid is set on the root while hasError is true"
+    ],
+    "focus": [
+      "BaseMap manages no focus; tab stops come from the map canvas and any interactive children"
+    ]
+  },
+  "behaviour": {
+    "states": ["default", "loading", "error"],
+    "rules": [
+      "initialViewState is the centre and zoom the map opens at; it is read once on mount",
+      "bounds (south-west and north-east corners) is fitted on load and whenever a new bounds value is passed, with fitBoundsPadding px around it; a zero-area bounds centres and zooms to SINGLE_POINT_ZOOM instead",
+      "isLoading makes the map invisible over the plain background without a spinner; hasError also disables pointer input and shows errorLabel with an error icon over a red tint",
+      "mapStyleUrl defaults to OpenFreeMap Liberty; env vars are not read",
+      "mapRef exposes the underlying MapLibre map for imperative calls such as easeTo; without it BaseMap keeps its own ref",
+      "onLoad fires once the style has loaded, after the initial bounds fit",
+      "The MapLibre library and its worker are loaded lazily on first render and shared by every map",
+      "The root fills its parent (size-full) with rounded corners; the parent or className must give it a height"
+    ]
+  },
+  "composition": {
+    "allowedParents": [],
+    "allowedChildren": [
+      "web-map/Source",
+      "web-map/Layer",
+      "web-map/Marker",
+      "web-map/map-user-location"
+    ],
+    "avoidCombinations": [
+      "web-map/map-marker directly in a BaseMap — it throws without a web-map/map-view around it",
+      "BaseMap inside a web-map/map-view — MapView already renders its own BaseMap; nesting draws a second map"
+    ],
+    "contexts": ["page section with an explicit height", "custom map component"]
+  },
+  "content": {
+    "labelRules": ["ariaLabel describes the content of the map, not the widget"],
+    "helperTextRules": [],
+    "errorRules": [
+      "errorLabel says the map could not load and what to do next, in one short sentence (default: 'Could not load map. Try again later.')",
+      "Pass errorLabel already translated; the package has no i18n dependency"
+    ]
+  },
+  "aiDecisionRules": [
+    {
+      "condition": "Markers must be selectable or hoverable",
+      "decision": "Use web-map/map-view instead of BaseMap",
+      "reason": "Selection and hover live in MapView's context; MapMarker cannot work without it"
+    },
+    {
+      "condition": "Custom code must move the camera (easeTo, fitBounds)",
+      "decision": "Pass a mapRef and call the MapLibre map from mapRef.current.getMap()",
+      "reason": "BaseMap has no camera props beyond initialViewState and bounds"
+    },
+    {
+      "condition": "bounds is derived from data",
+      "decision": "Memoise it",
+      "reason": "Every new bounds value re-fits the map and resets the user's pan and zoom"
+    }
+  ],
+  "relatedComponents": ["web-map/map-view", "web-map/map-user-location"]
+}