@elabs-ai/components-maps 4.2.0 → 5.0.0

package/src/map-canvas/map-canvas.tsx

@@ -16,8 +16,25 @@ import {
 import { Spinner, StatePanel, useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 
+import { createPlanCrs, type PlanCrs, type PlanExtent } from "../lib/plan-crs";
+import { warnMapOnce } from "../lib/warn-once";
 import { MapContext, type BasemapTheme } from "./map-context";
 import { useResolvedBasemapTheme } from "./use-resolved-basemap-theme";
+import {
+  MapFrameContext,
+  type MapFrameContextValue,
+  type MapFrameSide,
+  type MapHeight,
+  type MapResponsive,
+  mapBreakpointForWidth,
+  resolveMapHeightStyle,
+  useMeasuredMapBreakpoint,
+} from "../lib/use-map-breakpoint";
+import {
+  MapAnnotationKey,
+  MapAnnotationRegistryProvider,
+  useMapAnnotationRegistry,
+} from "../map-annotation/map-annotation";
 
 /**
  * Default basemaps: Carto's free light/dark GL styles. These serve ODbL-licensed
@@ -33,6 +50,9 @@ const defaultStyles = {
 // data visualizations (choropleths, arcs, dot maps) where you draw your own
 // layers and don't need a street basemap: `<MapCanvas blank>`. The transparent
 // background lets the themed container show through.
+/** Breathing room, in CSS pixels, between a fitted plan and the viewport edge. */
+const PLAN_FIT_PADDING = 24;
+
 const blankMapStyle: MapLibreGL.StyleSpecification = {
   version: 8,
   sources: {},
@@ -59,6 +79,93 @@ export interface MapViewport {
 
 export type MapStyleOption = string | MapLibreGL.StyleSpecification;
 
+/** `"mercator"` / `"globe"`, or a full MapLibre projection spec. */
+export type MapProjectionOption = "mercator" | "globe" | MapLibreGL.ProjectionSpecification;
+
+/** The gesture handlers static mode switches off (tooltips and hover keep working). */
+const GESTURE_HANDLERS = [
+  "scrollZoom",
+  "boxZoom",
+  "dragRotate",
+  "dragPan",
+  "keyboard",
+  "doubleClickZoom",
+  "touchZoomRotate",
+  "touchPitch",
+] as const;
+
+type GestureHandlerKey = (typeof GESTURE_HANDLERS)[number];
+
+const STATIC_HANDLER_OPTIONS = Object.fromEntries(
+  GESTURE_HANDLERS.map((key) => [key, false]),
+) as Record<GestureHandlerKey, false>;
+
+let warnedProjection = false;
+
+/**
+ * Apply a projection when this MapLibre build supports switching one
+ * (`setProjection`, MapLibre 5+); otherwise leave the map as it is and say so
+ * once — a globe is an extra, never a requirement.
+ */
+function applyProjection(map: MapLibreGL.Map, projection: MapLibreGL.ProjectionSpecification) {
+  if (typeof map.setProjection !== "function") {
+    if (!warnedProjection) {
+      warnedProjection = true;
+      console.warn(
+        "[@elabs-ai/components-maps] This MapLibre build cannot switch projections; `projection` is ignored.",
+      );
+    }
+    return;
+  }
+  map.setProjection(projection);
+}
+
+/**
+ * Hide (or restore) the basemap's OWN text labels — every symbol layer that
+ * draws a `text-field` (c-6 / c-11).
+ *
+ * A basemap's labels are drawn for a full-size map. Inside a 96 px inset they
+ * are sliced mid-word by the frame ("EUROP", "AMERIC") and louder than the
+ * globe they caption; on a locator they print a place name the editorial
+ * marker names again 16 px away. Both are the locator recipe's answer:
+ * the basemap draws the ground, the map's own labels do the naming.
+ *
+ * `hidden` records what THIS call turned off, so restoring never reveals a
+ * layer the style itself shipped hidden.
+ */
+function applyBasemapLabels(map: MapLibreGL.Map, visible: boolean, hidden: Set<string>) {
+  let style: MapLibreGL.StyleSpecification | undefined;
+  try {
+    style = map.getStyle?.();
+  } catch {
+    // style mid-reload
+    return;
+  }
+  if (!style?.layers) return;
+  if (visible) {
+    for (const id of hidden) {
+      if (map.getLayer(id)) map.setLayoutProperty(id, "visibility", "visible");
+    }
+    hidden.clear();
+    return;
+  }
+  for (const layer of style.layers) {
+    if (layer.type !== "symbol") continue;
+    if (!layer.layout || !("text-field" in layer.layout)) continue;
+    if (hidden.has(layer.id)) continue;
+    if (map.getLayoutProperty?.(layer.id, "visibility") === "none") continue;
+    map.setLayoutProperty(layer.id, "visibility", "none");
+    hidden.add(layer.id);
+  }
+}
+
+/** A box's measured size as a comparable key, or `null` while it has none. */
+function boxSize(node: HTMLElement): string | null {
+  const { width, height } = node.getBoundingClientRect();
+  if (!(width > 0) || !(height > 0)) return null;
+  return `${Math.round(width)}×${Math.round(height)}`;
+}
+
 /** The imperative handle exposed by `<MapCanvas ref>`: the MapLibre map itself. */
 export type MapCanvasRef = MapLibreGL.Map;
 
@@ -84,8 +191,37 @@ export type MapCanvasProps = {
    * visualizations. Ignored when an explicit `styles` prop is provided.
    */
   blank?: boolean;
-  /** Map projection type. Use `{ type: "globe" }` for a 3D globe view. */
-  projection?: MapLibreGL.ProjectionSpecification;
+  /**
+   * Draw the basemap's own place labels. `false` leaves the ground and hides
+   * every text label the basemap style carries, so the map's own labels
+   * (`MapMarker`'s `label`, `MapAnnotation`) are the only naming on it — the
+   * locator recipe, and the default inside `MapInset`, where a full-size
+   * label is sliced by the frame. Default `true`.
+   */
+  basemapLabels?: boolean;
+  /**
+   * Map projection: `"mercator"` (MapLibre's default) or `"globe"` for a 3D
+   * globe view, or a full MapLibre projection spec. Feature-detected: a
+   * MapLibre build that cannot switch projections ignores it (with a console
+   * note).
+   */
+  projection?: MapProjectionOption;
+  /**
+   * `false` makes the map STATIC — the editorial / locator default: no zoom,
+   * pan, rotate or keyboard handlers, the default cursor and no tab stop
+   * (leave `<MapControls>` out of a static map). Hover and click still reach
+   * layers and markers, so tooltips keep working. The viewport can still be set in code
+   * (`viewport`, the ref). Default `true`.
+   */
+  interactive?: boolean;
+  /**
+   * The map's height: CSS px, or `{ aspect }` (width ÷ height), optionally per
+   * tier — `{ base: { aspect: 1.6 }, narrow: { aspect: 1 } }`. Tiers are
+   * measured on the map's own width (`narrow` < 480 px, `medium` < 768 px).
+   * Unset, the map fills its parent as before; a parent with no height of its
+   * own gets `DEFAULT_MAP_HEIGHT` (1.6 : 1, square at `narrow`) instead of 0.
+   */
+  height?: MapResponsive<MapHeight>;
   /**
    * Controlled viewport. When provided together with `onViewportChange`, the
    * map becomes controlled and the viewport is driven by this prop.
@@ -99,12 +235,34 @@ export type MapCanvasProps = {
   onViewportChange?: (viewport: MapViewport) => void;
   /** Show a loading overlay on the map (e.g. while the app fetches map data). */
   loading?: boolean;
-} & Omit<MapLibreGL.MapOptions, "container" | "style">;
+  /**
+   * Turn the canvas into a CUSTOM (non-geographic) plan map: a floor plan, a
+   * factory layout, a train carriage, a rack elevation. Pass the plan's extent
+   * (`{ width, height }` in the plan's own units) or a `createPlanCrs(…)`
+   * result, and every layer inside then speaks PLAN coordinates instead of
+   * lng/lat — shapes, routes, markers and popups alike.
+   *
+   * The plan is fitted on mount, pan and zoom are clamped to its extent, and
+   * rotation and pitch are off (a rotated floor plan is unreadable). Pair it
+   * with `blank` and, for a picture under the shapes, `<MapPlanImage>`.
+   *
+   * The plan coordinate system is synthesized on Web Mercator, so it is not a
+   * georeference: distances belong to the plan, and a scale bar would lie.
+   */
+  plan?: PlanExtent | PlanCrs;
+  /**
+   * Fit a plan map to its extent on mount and whenever the extent changes
+   * (default: true). Ignored on a geographic map, and skipped when the camera
+   * is driven through `viewport`.
+   */
+  fitPlan?: boolean;
+} & Omit<MapLibreGL.MapOptions, "container" | "style" | "interactive">;
 
 function MapLoadingOverlay() {
+  const { t } = useLocale();
   return (
     <div className="absolute inset-0 z-10 flex items-center justify-center bg-background/50 backdrop-blur-xs">
-      <Spinner label="Loading map" className="size-5" />
+      <Spinner label={t("maps.canvas.loading")} className="size-5" />
     </div>
   );
 }
@@ -134,16 +292,33 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
     theme: themeProp,
     styles,
     blank = false,
-    projection,
+    basemapLabels = true,
+    projection: projectionProp,
     viewport,
     onViewportChange,
     loading = false,
+    interactive,
+    height,
+    plan: planProp,
+    fitPlan = true,
+    // Pulled out of `...props` so the constructor and the live plan-limit effect
+    // below resolve them the same way.
+    minZoom,
+    maxZoom,
+    maxBounds,
     ...props
   },
   ref,
 ) {
   const { t } = useLocale();
-  const containerRef = useRef<HTMLDivElement>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const [containerNode, setContainerNode] = useState<HTMLDivElement | null>(null);
+  const setContainer = useCallback((node: HTMLDivElement | null) => {
+    containerRef.current = node;
+    setContainerNode(node);
+  }, []);
+  const breakpoint = useMeasuredMapBreakpoint(containerNode);
+  const isStatic = interactive === false;
   const [mapInstance, setMapInstance] = useState<MapLibreGL.Map | null>(null);
   const [initFailed, setInitFailed] = useState(false);
   const [isLoaded, setIsLoaded] = useState(false);
@@ -158,10 +333,16 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
   const onViewportChangeRef = useRef(onViewportChange);
   onViewportChangeRef.current = onViewportChange;
 
+  // A string shorthand becomes a stable spec object; a spec object passes
+  // through as given.
+  const projection = useMemo<MapLibreGL.ProjectionSpecification | undefined>(
+    () => (typeof projectionProp === "string" ? { type: projectionProp } : projectionProp),
+    [projectionProp],
+  );
+
   // Read from the mount-only `styledata` handler below so a `projection` prop
   // change after mount isn't reapplied with the value captured at mount time.
   const projectionRef = useRef(projection);
-  projectionRef.current = projection;
 
   const mapStyles = useMemo(() => {
     // Explicit styles win. Otherwise `blank` opts into the transparent
@@ -178,6 +359,61 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
     return defaultStyles;
   }, [styles, blank]);
 
+  // Normalize `plan` from PRIMITIVES, so an inline `plan={{ width, height }}`
+  // literal keeps a stable coordinate system instead of re-running every layer
+  // effect on each render. A caller who passes their own memoized `PlanCrs`
+  // keeps that identity untouched.
+  const planIsCrs = typeof (planProp as PlanCrs | undefined)?.toLngLat === "function";
+  const planExtent = planIsCrs ? undefined : (planProp as PlanExtent | undefined);
+  const planWidth = planExtent?.width;
+  const planHeight = planExtent?.height;
+  const planOrigin = planExtent?.origin ?? "top-left";
+  const planUnit = planExtent?.unit ?? "px";
+  const derivedPlan = useMemo(
+    () =>
+      planWidth !== undefined && planHeight !== undefined
+        ? createPlanCrs({
+            width: planWidth,
+            height: planHeight,
+            origin: planOrigin,
+            unit: planUnit,
+          })
+        : null,
+    [planWidth, planHeight, planOrigin, planUnit],
+  );
+  const planCrs = planIsCrs ? ((planProp as PlanCrs) ?? null) : derivedPlan;
+
+  // A plan is a flat drawing: the globe would bend it, so refuse the pairing
+  // rather than render something the consumer cannot trust.
+  const projectionIsGlobe = !!projection && projection.type !== "mercator";
+  const effectiveProjection = planCrs && projectionIsGlobe ? undefined : projection;
+  projectionRef.current = effectiveProjection;
+  if (planCrs && projectionIsGlobe) {
+    warnMapOnce(
+      "plan-projection",
+      `Ignored projection "${projection?.type}" on a plan map: a plan is flat, and only the mercator projection keeps it undistorted.`,
+    );
+  }
+
+  // Camera options a plan needs. Merged UNDER `...props`, so an explicit prop
+  // always wins.
+  const planOptions = useMemo(() => {
+    if (!planCrs) return null;
+    return {
+      minZoom: planCrs.minZoom,
+      maxZoom: planCrs.maxZoom,
+      maxBounds: planCrs.maxBounds() as MapLibreGL.LngLatBoundsLike,
+      // A plan is 2D: rotation and tilt only make it harder to read.
+      dragRotate: false,
+      pitchWithRotate: false,
+      touchPitch: false,
+      bearing: 0,
+      pitch: 0,
+      // A plan is usually embedded in a page, so don't swallow the wheel.
+      cooperativeGestures: true,
+    };
+  }, [planCrs]);
+
   // Expose the map instance to the parent component.
   useImperativeHandle(ref, () => mapInstance as MapLibreGL.Map, [mapInstance]);
 
@@ -188,10 +424,52 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
     }
   }, []);
 
+  const heightRef = useRef(height);
+  heightRef.current = height;
+
+  // ── Keeping a bounds-framed map framed ─────────────────────────────────────
+  // MapLibre fits `bounds` ONCE, against the box it measures at construction.
+  // A box that settles later — a responsive height resolving after the first
+  // paint, a side panel opening, a tier flip — leaves the viewport fitted to a
+  // rectangle that no longer exists (a 348×218 fit kept on a 348×348 box put
+  // North America on a Lake Ontario locator). So: re-fit whenever the box
+  // changes size, until someone moves the map themselves.
+  const { bounds, fitBoundsOptions } = props;
+  const refitRef = useRef({ bounds, fitBoundsOptions });
+  refitRef.current = { bounds, fitBoundsOptions };
+  const isControlledRef = useRef(isControlled);
+  isControlledRef.current = isControlled;
+  /** `true` once a gesture (or the controlled `viewport`) owns the viewport. */
+  const userMovedRef = useRef(false);
+  /** The box size the current viewport was fitted against. */
+  const fittedSizeRef = useRef<string | null>(null);
+
+  const syncBox = useCallback((map: MapLibreGL.Map, node: HTMLElement) => {
+    const size = boxSize(node);
+    if (!size || size === fittedSizeRef.current) return;
+    fittedSizeRef.current = size;
+    map.resize();
+    const { bounds: currentBounds, fitBoundsOptions: currentOptions } = refitRef.current;
+    if (!currentBounds || userMovedRef.current || isControlledRef.current) return;
+    map.fitBounds(currentBounds, { ...currentOptions, duration: 0 });
+  }, []);
+
   // Initialize the map.
   useEffect(() => {
     if (!containerRef.current) return;
 
+    // The tier is measured in a layout effect whose re-render lands AFTER this
+    // effect, so the box may still carry the wide-tier height here. Size it for
+    // its real tier first: MapLibre sizes its canvas (and fits `bounds`) from
+    // the box at construction, and drops the first resize it observes.
+    Object.assign(
+      containerRef.current.style,
+      resolveMapHeightStyle(
+        heightRef.current,
+        mapBreakpointForWidth(containerRef.current.getBoundingClientRect().width),
+      ),
+    );
+
     const initialStyle = resolvedTheme === "dark" ? mapStyles.dark : mapStyles.light;
     currentStyleRef.current = initialStyle;
 
@@ -210,8 +488,24 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
         // `...props` below), or move to tiles licensed without the requirement via
         // `styles` / `blank`.
         attributionControl: false,
+        ...(planOptions ?? {}),
+        // `bounds` fits the plan in the very first frame, so a plan map never
+        // flashes at lng/lat 0,0 before the fit effect below runs. Skipped when
+        // the caller drives the camera themselves.
+        ...(planOptions && !viewport?.center
+          ? {
+              bounds: planCrs!.bounds as MapLibreGL.LngLatBoundsLike,
+              fitBoundsOptions: { padding: PLAN_FIT_PADDING, animate: false },
+            }
+          : {}),
+        ...(minZoom !== undefined ? { minZoom } : {}),
+        ...(maxZoom !== undefined ? { maxZoom } : {}),
+        ...(maxBounds !== undefined ? { maxBounds } : {}),
         ...props,
         ...viewport,
+        // Static mode: gestures off, but MapLibre's own `interactive` stays on —
+        // it would detach EVERY listener, tooltips and hover included.
+        ...(isStatic ? STATIC_HANDLER_OPTIONS : {}),
       });
     } catch {
       // MapLibre throws at construction when WebGL is unavailable (headless
@@ -228,7 +522,7 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
       styleTimeoutRef.current = setTimeout(() => {
         setIsStyleLoaded(true);
         if (projectionRef.current) {
-          map.setProjection(projectionRef.current);
+          applyProjection(map, projectionRef.current);
         }
       }, 100);
     };
@@ -253,9 +547,21 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
       onViewportChangeRef.current?.(getViewport(map));
     };
 
+    // A gesture carries the DOM event that caused it; our own `fitBounds` /
+    // `jumpTo` does not. Once a person has moved the map, a later box change
+    // resizes the canvas but must never yank the view back to `bounds`.
+    const handleMoveStart = (event?: { originalEvent?: unknown }) => {
+      if (event?.originalEvent) userMovedRef.current = true;
+    };
+
+    // The size the constructor fitted `bounds` against — the baseline every
+    // later box change is compared to.
+    fittedSizeRef.current = boxSize(containerRef.current);
+
     map.on("load", loadHandler);
     map.on("styledata", styleDataHandler);
     map.on("move", handleMove);
+    map.on("movestart", handleMoveStart);
     setMapInstance(map);
 
     return () => {
@@ -263,6 +569,7 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
       map.off("load", loadHandler);
       map.off("styledata", styleDataHandler);
       map.off("move", handleMove);
+      map.off("movestart", handleMoveStart);
       map.remove();
       setIsLoaded(false);
       setIsStyleLoaded(false);
@@ -316,9 +623,120 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
 
   // Sync projection when the prop changes after mount.
   useEffect(() => {
-    if (!mapInstance || !isStyleLoaded || !projection) return;
-    mapInstance.setProjection(projection);
-  }, [mapInstance, isStyleLoaded, projection]);
+    if (!mapInstance || !isStyleLoaded || !effectiveProjection) return;
+    applyProjection(mapInstance, effectiveProjection);
+  }, [mapInstance, isStyleLoaded, effectiveProjection]);
+
+  // Keep a plan map's camera limits live — unlike the geographic options above,
+  // which are init-time. A plan's extent is often only known once its image has
+  // decoded, and a multi-floor building can change it after mount.
+  useEffect(() => {
+    if (!mapInstance || !planCrs) return;
+    mapInstance.setMinZoom(minZoom ?? planCrs.minZoom);
+    mapInstance.setMaxZoom(maxZoom ?? planCrs.maxZoom);
+    mapInstance.setMaxBounds((maxBounds ?? planCrs.maxBounds()) as MapLibreGL.LngLatBoundsLike);
+  }, [mapInstance, planCrs, minZoom, maxZoom, maxBounds]);
+
+  // Fit the plan once per extent. Keyed on the extent rather than on the object
+  // so a floor swap at the same size does not yank the user's view.
+  const fittedExtentRef = useRef<string | null>(null);
+  useEffect(() => {
+    if (!mapInstance || !isLoaded || !planCrs || !fitPlan) return;
+    if (isControlled || viewport?.center) return;
+
+    const { width, height, origin } = planCrs.extent;
+    const extentKey = `${width}x${height}:${origin}`;
+    if (fittedExtentRef.current === extentKey) return;
+    fittedExtentRef.current = extentKey;
+
+    mapInstance.fitBounds(planCrs.bounds as MapLibreGL.LngLatBoundsLike, {
+      padding: PLAN_FIT_PADDING,
+      animate: false,
+    });
+  }, [mapInstance, isLoaded, planCrs, fitPlan, isControlled, viewport?.center]);
+
+  // Basemap labels on / off (c-6, c-11). Re-runs after every style load, so a
+  // theme flip (which swaps the whole style) does not bring the labels back.
+  const hiddenLabelLayersRef = useRef<Set<string>>(new Set());
+  useEffect(() => {
+    if (!mapInstance || !isStyleLoaded) return;
+    applyBasemapLabels(mapInstance, basemapLabels, hiddenLabelLayersRef.current);
+  }, [mapInstance, isStyleLoaded, basemapLabels, themeKey]);
+
+  // Static mode on / off after mount. Untouched until the map is first made
+  // static, so an interactive map keeps MapLibre's own setup exactly.
+  const handlerOptionsRef = useRef<Partial<Record<GestureHandlerKey, unknown>>>(props);
+  handlerOptionsRef.current = props;
+  const wasStaticRef = useRef(false);
+  useEffect(() => {
+    if (!mapInstance) return;
+    if (!isStatic && !wasStaticRef.current) return;
+    wasStaticRef.current = true;
+    for (const key of GESTURE_HANDLERS) {
+      const handler = mapInstance[key] as { enable?: () => void; disable?: () => void } | undefined;
+      if (isStatic) handler?.disable?.();
+      else if (handlerOptionsRef.current[key] !== false) handler?.enable?.();
+    }
+    // MapLibre's grab cursor hangs off this class; a static map keeps the
+    // default arrow (a layer's hover still sets its own pointer on the canvas).
+    mapInstance.getCanvasContainer().classList.toggle("maplibregl-interactive", !isStatic);
+    mapInstance.getCanvas().tabIndex = isStatic ? -1 : 0;
+  }, [mapInstance, isStatic]);
+
+  // c-10: the canvas is a tab stop MapLibre owns, so before this it painted
+  // the BROWSER's default focus ring (`1px auto rgb(0, 95, 204)` in light,
+  // `rgb(153, 200, 255)` in dark) — visible, but not the theme's. The house
+  // indicator is a utility class, so the element simply wears it.
+  useEffect(() => {
+    if (!mapInstance) return;
+    mapInstance.getCanvas()?.classList.add("focus-ring");
+  }, [mapInstance]);
+
+  // Watch the box: any size change resizes the canvas and re-fits `bounds`.
+  useEffect(() => {
+    if (!mapInstance || !containerNode) return undefined;
+    const sync = () => syncBox(mapInstance, containerNode);
+    sync();
+    if (typeof ResizeObserver === "undefined") return undefined;
+    const observer = new ResizeObserver(sync);
+    observer.observe(containerNode);
+    return () => observer.disconnect();
+  }, [mapInstance, containerNode, syncBox]);
+
+  // A tier change can swap the box's height (the default goes square at
+  // `narrow`); sync at commit rather than wait on the observer's next frame.
+  const heightStyle = resolveMapHeightStyle(height, breakpoint);
+  const heightKey = `${heightStyle.height ?? ""}|${heightStyle.aspectRatio ?? ""}`;
+  const appliedHeightKeyRef = useRef(heightKey);
+  useEffect(() => {
+    if (!mapInstance || !containerNode || heightKey === appliedHeightKeyRef.current) return;
+    appliedHeightKeyRef.current = heightKey;
+    syncBox(mapInstance, containerNode);
+  }, [mapInstance, containerNode, heightKey, syncBox]);
+
+  // Furniture outside the map box (legends `above` / `below`, the narrow
+  // annotation key) portals into strips rendered only while something asks.
+  const [slotRequests, setSlotRequests] = useState<Record<MapFrameSide, number>>({
+    above: 0,
+    below: 0,
+  });
+  const [aboveEl, setAboveEl] = useState<HTMLDivElement | null>(null);
+  const [belowEl, setBelowEl] = useState<HTMLDivElement | null>(null);
+  const requestSlot = useCallback((side: MapFrameSide) => {
+    setSlotRequests((prev) => ({ ...prev, [side]: prev[side] + 1 }));
+    return () => setSlotRequests((prev) => ({ ...prev, [side]: Math.max(0, prev[side] - 1) }));
+  }, []);
+  const frameValue = useMemo<MapFrameContextValue>(
+    () => ({
+      breakpoint,
+      interactive: !isStatic,
+      slots: { above: aboveEl, below: belowEl },
+      requestSlot,
+    }),
+    [breakpoint, isStatic, aboveEl, belowEl, requestSlot],
+  );
+  const annotations = useMapAnnotationRegistry(breakpoint);
+  const showBelow = slotRequests.below > 0 || annotations.rows.length > 0;
 
   const contextValue = useMemo(
     () => ({
@@ -326,8 +744,10 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
       isLoaded: isLoaded && isStyleLoaded,
       resolvedTheme,
       themeKey,
+      plan: planCrs,
+      loading,
     }),
-    [mapInstance, isLoaded, isStyleLoaded, resolvedTheme, themeKey],
+    [mapInstance, isLoaded, isStyleLoaded, resolvedTheme, themeKey, planCrs, loading],
   );
 
   if (initFailed) {
@@ -345,11 +765,31 @@ export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCa
 
   return (
     <MapContext.Provider value={contextValue}>
-      <div ref={containerRef} className={cn("relative h-full w-full", className)}>
-        {(!isLoaded || loading) && <MapLoadingOverlay />}
-        {/* SSR-safe: children render only when the map exists on the client. */}
-        {mapInstance && children}
-      </div>
+      <MapFrameContext.Provider value={frameValue}>
+        <MapAnnotationRegistryProvider value={annotations.value}>
+          {slotRequests.above > 0 && (
+            <div ref={setAboveEl} data-slot="map-canvas-above" className="pb-2" />
+          )}
+          <div
+            ref={setContainer}
+            data-slot="map-canvas"
+            data-map-breakpoint={breakpoint}
+            data-interactive={isStatic ? "false" : undefined}
+            className={cn("relative h-full w-full", className)}
+            style={heightStyle}
+          >
+            {(!isLoaded || loading) && <MapLoadingOverlay />}
+            {/* SSR-safe: children render only when the map exists on the client. */}
+            {mapInstance && children}
+          </div>
+          {showBelow && (
+            <div data-slot="map-canvas-below" className="flex flex-col gap-2 pt-2">
+              <div ref={setBelowEl} data-slot="map-canvas-below-furniture" className="contents" />
+              {annotations.rows.length > 0 && <MapAnnotationKey rows={annotations.rows} />}
+            </div>
+          )}
+        </MapAnnotationRegistryProvider>
+      </MapFrameContext.Provider>
     </MapContext.Provider>
   );
 });

package/src/map-canvas/map-context.ts

@@ -3,6 +3,8 @@
 import type MapLibreGL from "maplibre-gl";
 import { createContext, use } from "react";
 
+import type { PlanCrs } from "../lib/plan-crs";
+
 /** Light-or-dark flavor of the active basemap (derived from the brand theme). */
 export type BasemapTheme = "light" | "dark";
 
@@ -18,6 +20,15 @@ export interface MapContextValue {
    * as a dependency key to re-resolve semantic token colors for WebGL paint.
    */
   themeKey: string;
+  /**
+   * The plan coordinate system when this canvas is a CUSTOM (non-geographic)
+   * plan map — a floor plan, factory layout or carriage — and `null` for an
+   * ordinary geographic map. Layer components read it to convert the plan
+   * coordinates they are handed, and to report plan coordinates back.
+   */
+  plan: PlanCrs | null;
+  /** True while the consumer has asked for a loading overlay over the map. */
+  loading: boolean;
 }
 
 export const MapContext = createContext<MapContextValue | null>(null);

package/src/map-cluster-layer/map-cluster-layer.tsx

@@ -5,6 +5,7 @@ import { useEffect, useId, useMemo } from "react";
 
 import { useMap } from "../map-canvas/map-context";
 import { useTokenColor } from "../lib/use-token-color";
+import { warnMapOnce } from "../lib/warn-once";
 
 export type MapClusterLayerProps<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> =
   {
@@ -38,6 +39,11 @@ const DEFAULT_CLUSTER_THRESHOLDS: [number, number] = [100, 750];
  * Clustered point rendering for large point datasets. Cluster circles step
  * through the status tokens (success → warning → destructive) as the point
  * count grows; strokes and count labels use the page surface for contrast.
+ *
+ * NOT for a plan map. The count inside each circle is a `symbol` `text-field`,
+ * and a blank style — which every plan uses — ships no glyph endpoint, so the
+ * counts would silently render as nothing at all. Cluster plan points yourself
+ * and draw the groups with `MapGeoJSON`, or put the count in the DOM overlay.
  */
 export function MapClusterLayer<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties>({
   data,
@@ -49,13 +55,20 @@ export function MapClusterLayer<P extends GeoJSON.GeoJsonProperties = GeoJSON.Ge
   onPointClick,
   onClusterClick,
 }: MapClusterLayerProps<P>) {
-  const { map, isLoaded } = useMap();
+  const { map, isLoaded, plan } = useMap();
   const id = useId();
   const sourceId = `cluster-source-${id}`;
   const clusterLayerId = `clusters-${id}`;
   const clusterCountLayerId = `cluster-count-${id}`;
   const unclusteredLayerId = `unclustered-point-${id}`;
 
+  if (plan) {
+    warnMapOnce(
+      "cluster-layer-plan",
+      "<MapClusterLayer> is not for a plan map: its count label is a symbol text-field, and a plan's blank style has no glyph endpoint, so the counts render as nothing.",
+    );
+  }
+
   const success = useTokenColor("--success");
   const warning = useTokenColor("--warning");
   const destructive = useTokenColor("--destructive");