@elabs-ai/components-maps 4.2.0 → 5.1.0

package/src/lib/route-arrow.test.ts

@@ -0,0 +1,88 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { createRouteArrowImage, ROUTE_ARROW_SIZE, routeArrowImageId } from "./route-arrow";
+
+interface Stroked {
+  points: [number, number][];
+  strokeStyle: string;
+}
+
+/** A 2D context that records the path instead of rasterizing it. */
+function stubCanvasContext() {
+  const drawn: Stroked = { points: [], strokeStyle: "" };
+
+  vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockImplementation(function (kind: string) {
+    if (kind !== "2d") return null;
+    const context = {
+      set strokeStyle(value: string) {
+        drawn.strokeStyle = value;
+      },
+      get strokeStyle() {
+        return drawn.strokeStyle;
+      },
+      lineWidth: 0,
+      lineCap: "butt",
+      lineJoin: "miter",
+      clearRect: () => {},
+      beginPath: () => {},
+      moveTo: (x: number, y: number) => drawn.points.push([x, y]),
+      lineTo: (x: number, y: number) => drawn.points.push([x, y]),
+      stroke: () => {},
+      getImageData: (_x: number, _y: number, width: number, height: number) => ({
+        data: new Uint8ClampedArray(width * height * 4),
+      }),
+    };
+    return context as unknown as CanvasRenderingContext2D;
+  });
+
+  return drawn;
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("routeArrowImageId", () => {
+  it("is one image per route, since the ink is per route", () => {
+    expect(routeArrowImageId("aisle")).toBe("route-arrow-aisle");
+    expect(routeArrowImageId("aisle")).not.toBe(routeArrowImageId("conveyor"));
+  });
+});
+
+describe("createRouteArrowImage", () => {
+  it("returns null with no 2D context, so the caller leaves the layer out", () => {
+    // jsdom, unstubbed: an arrow layer pointing at a missing image draws nothing
+    // and warns every frame, so the caller must be able to tell.
+    expect(createRouteArrowImage("#000")).toBeNull();
+  });
+
+  it("draws a chevron pointing along +x, in the ink it was given", () => {
+    const drawn = stubCanvasContext();
+
+    const image = createRouteArrowImage("rgb(4, 5, 6)");
+
+    expect(image).toEqual({
+      width: ROUTE_ARROW_SIZE,
+      height: ROUTE_ARROW_SIZE,
+      data: new Uint8ClampedArray(ROUTE_ARROW_SIZE * ROUTE_ARROW_SIZE * 4),
+    });
+    expect(drawn.strokeStyle).toBe("rgb(4, 5, 6)");
+
+    // Three points: back-top, tip, back-bottom. The tip is the rightmost point
+    // and sits on the middle row — MapLibre aligns a line-placed symbol's x axis
+    // with the line, so +x is "forward".
+    expect(drawn.points).toHaveLength(3);
+    const [top, tip, bottom] = drawn.points as [
+      [number, number],
+      [number, number],
+      [number, number],
+    ];
+    expect(tip[0]).toBeGreaterThan(top[0]);
+    expect(tip[0]).toBeGreaterThan(bottom[0]);
+    expect(tip[1]).toBeCloseTo(ROUTE_ARROW_SIZE / 2, 5);
+    expect(top[1]).toBeLessThan(tip[1]);
+    expect(bottom[1]).toBeGreaterThan(tip[1]);
+    // Symmetric about the middle row, so the chevron is not lopsided.
+    expect(top[1] + bottom[1]).toBeCloseTo(ROUTE_ARROW_SIZE, 5);
+  });
+});

package/src/lib/route-arrow.ts

@@ -0,0 +1,59 @@
+/**
+ * The direction chevron for `<MapRoute direction>`, drawn on a canvas and
+ * registered with `map.addImage`.
+ *
+ * An icon rather than a text glyph on purpose: a blank MapLibre style ships no
+ * glyph endpoint, so a `symbol` layer's `text-field` renders nothing at all —
+ * while `icon-image` needs no network and no sprite.
+ */
+
+/** Tile edge, in px. Drawn at `pixelRatio: 2`, so it reads ~12 px on screen. */
+export const ROUTE_ARROW_SIZE = 24;
+
+/** Image id for one route's chevron. Per route, because the ink is per route. */
+export function routeArrowImageId(routeId: string): string {
+  return `route-arrow-${routeId}`;
+}
+
+/** A raw RGBA image MapLibre accepts, without depending on the DOM's `ImageData`. */
+export interface RouteArrowImage {
+  width: number;
+  height: number;
+  data: Uint8ClampedArray;
+}
+
+/**
+ * A chevron pointing along +x. MapLibre aligns a line-placed symbol's x axis
+ * with the line's direction, so +x is "forward"; `icon-rotate: 180` is backward.
+ *
+ * Returns `null` where there is no 2D context (jsdom) — the caller then leaves
+ * the arrow layer out rather than pointing it at a missing image, which
+ * MapLibre would draw as nothing while warning on every frame.
+ */
+export function createRouteArrowImage(ink: string): RouteArrowImage | null {
+  if (typeof document === "undefined") return null;
+
+  const canvas = document.createElement("canvas");
+  canvas.width = ROUTE_ARROW_SIZE;
+  canvas.height = ROUTE_ARROW_SIZE;
+  const context = canvas.getContext("2d");
+  if (!context) return null;
+
+  const size = ROUTE_ARROW_SIZE;
+  const inset = size * 0.22;
+  const mid = size / 2;
+
+  context.clearRect(0, 0, size, size);
+  context.strokeStyle = ink;
+  context.lineWidth = size * 0.16;
+  context.lineCap = "round";
+  context.lineJoin = "round";
+  context.beginPath();
+  context.moveTo(inset, inset);
+  context.lineTo(size - inset, mid);
+  context.lineTo(inset, size - inset);
+  context.stroke();
+
+  const image = context.getImageData(0, 0, size, size);
+  return { width: size, height: size, data: image.data };
+}

package/src/lib/use-map-breakpoint.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_MAP_HEIGHT,
+  MAP_BREAKPOINT_THRESHOLDS,
+  mapBreakpointForWidth,
+  resolveMapHeightStyle,
+  resolveMapResponsive,
+} from "./use-map-breakpoint";
+
+describe("map breakpoints (a documented copy of the charts tiers)", () => {
+  it("uses the charts thresholds: narrow < 480, medium < 768", () => {
+    expect(MAP_BREAKPOINT_THRESHOLDS).toEqual({ narrow: 480, medium: 768 });
+    expect(mapBreakpointForWidth(348)).toBe("narrow");
+    expect(mapBreakpointForWidth(479.5)).toBe("narrow");
+    expect(mapBreakpointForWidth(480)).toBe("medium");
+    expect(mapBreakpointForWidth(568)).toBe("medium");
+    expect(mapBreakpointForWidth(768)).toBe("wide");
+    expect(mapBreakpointForWidth(868)).toBe("wide");
+  });
+
+  it("treats an unmeasured width as wide", () => {
+    expect(mapBreakpointForWidth(0)).toBe("wide");
+    expect(mapBreakpointForWidth(Number.NaN)).toBe("wide");
+  });
+
+  it("resolves per-tier values desktop-first", () => {
+    const value = { base: "a", medium: "b", narrow: "c" };
+    expect(resolveMapResponsive(value, "wide")).toBe("a");
+    expect(resolveMapResponsive(value, "medium")).toBe("b");
+    expect(resolveMapResponsive(value, "narrow")).toBe("c");
+    expect(resolveMapResponsive({ base: true, narrow: false }, "medium")).toBe(true);
+    expect(resolveMapResponsive({ base: true, narrow: false }, "narrow")).toBe(false);
+    expect(resolveMapResponsive(false, "narrow")).toBe(false);
+  });
+
+  it("defaults the height to 1.6 : 1, square at narrow", () => {
+    expect(DEFAULT_MAP_HEIGHT).toEqual({ base: { aspect: 1.6 }, narrow: { aspect: 1 } });
+    expect(resolveMapHeightStyle(undefined, "wide")).toEqual({
+      aspectRatio: "1.6 / 1",
+      transitionProperty: "none",
+    });
+    expect(resolveMapHeightStyle(undefined, "narrow")).toEqual({
+      aspectRatio: "1 / 1",
+      transitionProperty: "none",
+    });
+  });
+
+  // The engine measures this box. A transitioned height/aspect only lands on
+  // the next animation frame — and the reduced-motion clamp gives EVERY element
+  // a 0.01 ms duration, so "no motion" is exactly where the map used to be
+  // measured mid-change and fit its bounds to a box that never existed.
+  it("never lets the box's geometry animate, whichever branch sets it", () => {
+    for (const style of [
+      resolveMapHeightStyle(undefined, "narrow"),
+      resolveMapHeightStyle(420, "narrow"),
+      resolveMapHeightStyle({ aspect: 2 }, "wide"),
+    ]) {
+      expect(style.transitionProperty).toBe("none");
+    }
+  });
+
+  it("lets an explicit height win, per tier", () => {
+    expect(resolveMapHeightStyle(420, "narrow")).toEqual({
+      height: 420,
+      transitionProperty: "none",
+    });
+    expect(resolveMapHeightStyle({ base: { aspect: 2 }, narrow: 360 }, "wide")).toEqual({
+      height: "auto",
+      aspectRatio: "2 / 1",
+      transitionProperty: "none",
+    });
+    expect(resolveMapHeightStyle({ base: { aspect: 2 }, narrow: 360 }, "narrow")).toEqual({
+      height: 360,
+      transitionProperty: "none",
+    });
+    // An invalid height falls back to the default instead of collapsing.
+    expect(resolveMapHeightStyle(-5, "wide")).toEqual({
+      aspectRatio: "1.6 / 1",
+      transitionProperty: "none",
+    });
+  });
+});

package/src/lib/use-map-breakpoint.ts

@@ -0,0 +1,238 @@
+"use client";
+
+/**
+ * The map's responsive contract: container tiers, `MapResponsive<T>` and the
+ * frame context `<MapCanvas>` provides to its furniture (RM-125).
+ *
+ * A DELIBERATE COPY of `@elabs-ai/components-charts`' `chart-breakpoint.ts`
+ * (ADR 0039), with the same thresholds and the same desktop-first
+ * `{ base, medium?, narrow? }` shape. `maps` may not import `charts` (both are
+ * layer-2 leaves — `pnpm check --rule dep-direction`), so the few lines live
+ * here too. Change a threshold in both files or in neither.
+ *
+ * - Three container tiers, measured on the MAP's own width, never the
+ *   viewport: `narrow` (< 480 px), `medium` (< 768 px), `wide`.
+ * - `MapResponsive<T>`: one value, or `{ base, medium?, narrow? }` — an
+ *   override applies at its tier and every narrower tier that sets nothing.
+ *   A plain value structurally matches `charts`' `Responsive<T>`, so one
+ *   object can drive a chart and a map.
+ */
+
+import {
+  type CSSProperties,
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useState,
+} from "react";
+
+// ── Tiers ────────────────────────────────────────────────────────────────────
+
+/** A map container's width tier — the same three tiers as a chart's. */
+export type MapBreakpoint = "narrow" | "medium" | "wide";
+
+/** Every tier, narrowest first. */
+export const MAP_BREAKPOINTS: readonly MapBreakpoint[] = ["narrow", "medium", "wide"];
+
+/**
+ * A width (CSS px) below `narrow` is narrow; below `medium` is medium; anything
+ * else is wide. A boundary belongs to the wider tier (480 → medium). Same
+ * numbers as `CHART_BREAKPOINT_THRESHOLDS`.
+ */
+export const MAP_BREAKPOINT_THRESHOLDS = { narrow: 480, medium: 768 } as const;
+
+/**
+ * The tier for a measured container width. `0` or a non-finite width means
+ * "not measured yet" (server render, first pass, `display: none`) and
+ * resolves to `wide`, so a first paint matches the pre-tier layout.
+ */
+export function mapBreakpointForWidth(width: number): MapBreakpoint {
+  if (!Number.isFinite(width) || width <= 0) return "wide";
+  if (width < MAP_BREAKPOINT_THRESHOLDS.narrow) return "narrow";
+  if (width < MAP_BREAKPOINT_THRESHOLDS.medium) return "medium";
+  return "wide";
+}
+
+// ── MapResponsive<T> ─────────────────────────────────────────────────────────
+
+/**
+ * Per-tier values, desktop-first: `base` is the WIDE value (the opposite of
+ * Tailwind's unprefixed, mobile-first class); overrides go down.
+ */
+export interface MapResponsiveByBreakpoint<T> {
+  /** The value at `wide`, and the fallback for every tier that sets nothing. */
+  base: T;
+  /** At `medium` — and at `narrow` too, unless `narrow` is set. */
+  medium?: T;
+  /** At `narrow` only. */
+  narrow?: T;
+}
+
+/**
+ * One value for every tier, or per-tier values. `T` must never be an object
+ * type with its own `base` key (that key marks the per-tier form). Read it
+ * through {@link resolveMapResponsive} / {@link useMapResponsive}.
+ */
+export type MapResponsive<T> = T | MapResponsiveByBreakpoint<T>;
+
+/** True for the per-tier form: a plain object with its own `base` key. */
+export function isMapResponsiveByBreakpoint<T>(
+  value: MapResponsive<T>,
+): value is MapResponsiveByBreakpoint<T> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.prototype.hasOwnProperty.call(value, "base")
+  );
+}
+
+/**
+ * The value for `breakpoint`: `wide` → `base`; `medium` → `medium ?? base`;
+ * `narrow` → `narrow ?? medium ?? base`. "Not set" means `undefined`.
+ */
+export function resolveMapResponsive<T>(value: MapResponsive<T>, breakpoint: MapBreakpoint): T {
+  if (!isMapResponsiveByBreakpoint(value)) return value as T;
+  if (breakpoint === "wide") return value.base;
+  if (breakpoint === "narrow" && value.narrow !== undefined) return value.narrow;
+  return value.medium !== undefined ? value.medium : value.base;
+}
+
+// ── Height ───────────────────────────────────────────────────────────────────
+
+/** CSS px, or the map's width ÷ height (`{ aspect: 2 }` = twice as wide as tall). */
+export type MapHeight = number | { aspect: number };
+
+/**
+ * The height a `<MapCanvas>` falls back to when its parent gives it none:
+ * 1.6 : 1, and square at `narrow` — an aspect-locked map at 380 px would
+ * otherwise shrink to a strip nobody can read.
+ */
+export const DEFAULT_MAP_HEIGHT: MapResponsiveByBreakpoint<MapHeight> = {
+  base: { aspect: 1.6 },
+  narrow: { aspect: 1 },
+};
+
+function validHeight(value: MapHeight | undefined): MapHeight | undefined {
+  if (typeof value === "number") return Number.isFinite(value) && value > 0 ? value : undefined;
+  if (value && Number.isFinite(value.aspect) && value.aspect > 0) return value;
+  return undefined;
+}
+
+/**
+ * The map box's geometry is LAYOUT THE ENGINE MEASURES, so it must never
+ * interpolate. `transition-property` defaults to `all`, and the house
+ * reduced-motion clamp sets `transition-duration: 0.01ms !important` on every
+ * element — which turns a height / aspect-ratio change into a (very short)
+ * transition that still lands one animation frame later. Under a busy WebGL
+ * first paint that frame arrived ~0.7 s late, so MapLibre measured the box
+ * mid-transition (348×218 on a box that ends up 348×348) and fitted `bounds`
+ * to a rectangle that never existed. `none` beats any stylesheet from the
+ * inline style, and the clamp only forces DURATIONS, never the property list.
+ */
+const NO_GEOMETRY_TRANSITION = { transitionProperty: "none" } as const;
+
+/**
+ * The container style for a `height` at `breakpoint`. An explicit `height`
+ * sets the box outright (`height: auto` releases the `h-full` class for an
+ * aspect). Without one, only an `aspect-ratio` is set — CSS ignores it while
+ * the parent gives the map a definite height, so a map in a sized parent
+ * looks exactly as before; a map in an unsized parent stops collapsing to 0.
+ * Every branch pins {@link NO_GEOMETRY_TRANSITION} so the box resizes in the
+ * same frame the rule changes.
+ */
+export function resolveMapHeightStyle(
+  height: MapResponsive<MapHeight> | undefined,
+  breakpoint: MapBreakpoint,
+): CSSProperties {
+  const own =
+    height === undefined ? undefined : validHeight(resolveMapResponsive(height, breakpoint));
+  if (typeof own === "number") return { ...NO_GEOMETRY_TRANSITION, height: own };
+  if (own) return { ...NO_GEOMETRY_TRANSITION, height: "auto", aspectRatio: `${own.aspect} / 1` };
+  const fallback = resolveMapResponsive(DEFAULT_MAP_HEIGHT, breakpoint);
+  return typeof fallback === "number"
+    ? { ...NO_GEOMETRY_TRANSITION }
+    : { ...NO_GEOMETRY_TRANSITION, aspectRatio: `${fallback.aspect} / 1` };
+}
+
+// ── Measuring ────────────────────────────────────────────────────────────────
+
+/**
+ * Measures `node` with a `ResizeObserver` and returns its tier. Re-renders
+ * only when the TIER changes.
+ */
+export function useMeasuredMapBreakpoint(node: Element | null): MapBreakpoint {
+  const [breakpoint, setBreakpoint] = useState<MapBreakpoint>("wide");
+  // Layout effect: the first measure lands before paint, so a narrow map never
+  // flashes its wide furniture.
+  useLayoutEffect(() => {
+    if (!node) return undefined;
+    const update = (width: number) => {
+      const next = mapBreakpointForWidth(width);
+      setBreakpoint((prev) => (prev === next ? prev : next));
+    };
+    update(node.getBoundingClientRect().width);
+    if (typeof ResizeObserver === "undefined") return undefined;
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[entries.length - 1];
+      if (entry) update(entry.contentRect.width);
+    });
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [node]);
+  return breakpoint;
+}
+
+// ── Frame context ────────────────────────────────────────────────────────────
+
+/** Where furniture outside the map box goes: the strip above or below it. */
+export type MapFrameSide = "above" | "below";
+
+export interface MapFrameContextValue {
+  /** The map container's measured tier. */
+  breakpoint: MapBreakpoint;
+  /** `false` when the canvas is static (`<MapCanvas interactive={false}>`). */
+  interactive: boolean;
+  /** The strips around the map box; `null` until something asks for one. */
+  slots: Record<MapFrameSide, HTMLElement | null>;
+  /** Ask the canvas to render a strip; returns the release function. */
+  requestSlot: (side: MapFrameSide) => () => void;
+}
+
+const noopRelease = () => {};
+
+const DEFAULT_FRAME: MapFrameContextValue = {
+  breakpoint: "wide",
+  interactive: true,
+  slots: { above: null, below: null },
+  requestSlot: () => noopRelease,
+};
+
+export const MapFrameContext = createContext<MapFrameContextValue>(DEFAULT_FRAME);
+
+/** The frame `<MapCanvas>` provides: tier, static flag, outside strips. */
+export function useMapFrame(): MapFrameContextValue {
+  return useContext(MapFrameContext);
+}
+
+/** The enclosing map's tier (`wide` outside a `<MapCanvas>`). */
+export function useMapBreakpoint(): MapBreakpoint {
+  return useContext(MapFrameContext).breakpoint;
+}
+
+/** `value` resolved at the enclosing map's tier. */
+export function useMapResponsive<T>(value: MapResponsive<T>): T {
+  return resolveMapResponsive(value, useMapBreakpoint());
+}
+
+/**
+ * The strip above / below the map box to portal into, or `null` while it is
+ * not needed (`side` is `null`) or not mounted yet. Asking renders the strip;
+ * the canvas drops it again when nothing asks.
+ */
+export function useMapFrameSlot(side: MapFrameSide | null): HTMLElement | null {
+  const { slots, requestSlot } = useContext(MapFrameContext);
+  useEffect(() => (side ? requestSlot(side) : undefined), [side, requestSlot]);
+  return side ? slots[side] : null;
+}

package/src/lib/use-plan-projection.ts

@@ -0,0 +1,157 @@
+"use client";
+
+import type MapLibreGL from "maplibre-gl";
+import { useCallback, useEffect, useRef } from "react";
+
+import type { PlanCrs } from "./plan-crs";
+import type { MapPlanRegion } from "./plan-regions";
+
+/** Where a region ended up on screen, in CSS pixels relative to the canvas. */
+export interface PlanScreenBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface UsePlanProjectionOptions {
+  map: MapLibreGL.Map | null;
+  plan: PlanCrs | null;
+  /**
+   * The regions to track. Keep this array MEMOIZED: it is an effect dependency,
+   * and a fresh array every render re-binds the map listeners every render.
+   */
+  regions: readonly MapPlanRegion[];
+  /** Turn tracking off (while the map is still loading, say). */
+  enabled?: boolean;
+  /** Called after each frame's DOM writes, with the boxes that were written. */
+  onFrame?: (boxes: ReadonlyMap<string, PlanScreenBox>) => void;
+}
+
+/**
+ * ONE projection pass for every plan overlay element, coalesced into a single
+ * `requestAnimationFrame` and writing straight to the DOM — no React state per
+ * frame, no per-element listener. A MapLibre `Marker` binds its own `move`
+ * listener and projects itself, so forty rooms would mean eighty listeners and
+ * forty uncoordinated writes; this is one listener set and one write pass.
+ *
+ * Each region is projected from its FOUR plan corners to a screen box, so the
+ * box stays right even where the projection is not a plain scale.
+ */
+export function usePlanProjection({
+  map,
+  plan,
+  regions,
+  enabled = true,
+  onFrame,
+}: UsePlanProjectionOptions) {
+  const elementsRef = useRef(new Map<string, HTMLElement>());
+  const boxesRef = useRef(new Map<string, PlanScreenBox>());
+  const frameRef = useRef<number | null>(null);
+  const latestRef = useRef({ map, plan, regions, enabled, onFrame });
+  latestRef.current = { map, plan, regions, enabled, onFrame };
+
+  /** The whole write pass. Reads refs only, so it never needs re-creating. */
+  const write = useCallback(() => {
+    frameRef.current = null;
+    const {
+      map: currentMap,
+      plan: currentPlan,
+      regions: currentRegions,
+      enabled: isEnabled,
+      onFrame: notify,
+    } = latestRef.current;
+    if (!currentMap || !currentPlan || !isEnabled) return;
+
+    const boxes = boxesRef.current;
+    boxes.clear();
+
+    for (const region of currentRegions) {
+      const element = elementsRef.current.get(region.id);
+      const { x, y, width, height } = region.bounds;
+      const corners: [number, number][] = [
+        [x, y],
+        [x + width, y],
+        [x + width, y + height],
+        [x, y + height],
+      ];
+
+      let minX = Number.POSITIVE_INFINITY;
+      let minY = Number.POSITIVE_INFINITY;
+      let maxX = Number.NEGATIVE_INFINITY;
+      let maxY = Number.NEGATIVE_INFINITY;
+      for (const [cornerX, cornerY] of corners) {
+        const point = currentMap.project(currentPlan.toLngLat({ x: cornerX, y: cornerY }));
+        if (point.x < minX) minX = point.x;
+        if (point.y < minY) minY = point.y;
+        if (point.x > maxX) maxX = point.x;
+        if (point.y > maxY) maxY = point.y;
+      }
+
+      const box: PlanScreenBox = {
+        x: minX,
+        y: minY,
+        width: Math.max(1, maxX - minX),
+        height: Math.max(1, maxY - minY),
+      };
+      boxes.set(region.id, box);
+
+      if (!element) continue;
+      // Physical `left`/`top`, deliberately: `map.project` returns screen
+      // pixels, which do not mirror in RTL — a logical inset would put every
+      // region on the wrong side of the canvas.
+      element.style.left = "0px";
+      element.style.top = "0px";
+      element.style.width = `${Math.round(box.width)}px`;
+      element.style.height = `${Math.round(box.height)}px`;
+      element.style.transform = `translate(${Math.round(box.x)}px, ${Math.round(box.y)}px)`;
+    }
+
+    notify?.(boxes);
+  }, []);
+
+  /** Ask for a frame. Repeated calls inside one frame collapse into one pass. */
+  const refresh = useCallback(() => {
+    if (!latestRef.current.enabled) return;
+    if (frameRef.current != null) return;
+    if (typeof requestAnimationFrame !== "function") {
+      write();
+      return;
+    }
+    frameRef.current = requestAnimationFrame(write);
+  }, [write]);
+
+  /** `ref` callback for a region's element. */
+  const register = useCallback(
+    (id: string, element: HTMLElement | null) => {
+      if (element) elementsRef.current.set(id, element);
+      else elementsRef.current.delete(id);
+      refresh();
+    },
+    [refresh],
+  );
+
+  useEffect(() => {
+    if (!map || !plan || !enabled) return;
+
+    // Write once synchronously, so the first paint already has the geometry
+    // rather than a stack of boxes at the origin.
+    write();
+
+    map.on("move", refresh);
+    map.on("moveend", refresh);
+    map.on("resize", refresh);
+
+    return () => {
+      map.off("move", refresh);
+      map.off("moveend", refresh);
+      map.off("resize", refresh);
+      if (frameRef.current != null) {
+        cancelAnimationFrame(frameRef.current);
+        frameRef.current = null;
+      }
+    };
+  }, [map, plan, enabled, regions, refresh, write]);
+
+  return { register, refresh, boxes: boxesRef };
+}

package/src/lib/warn-once.ts

@@ -0,0 +1,21 @@
+/**
+ * Dev-only warnings for the silent failure modes a map wrapper cannot type away
+ * — a plan coordinate handed to a geographic canvas, a missing `promoteId`, a
+ * GeoJSON URL that cannot be transformed. Mirrors `warnChartOnce` in
+ * `@elabs-ai/components-charts` (kept local: `dep-direction` forbids the import).
+ */
+
+const warned = new Set<string>();
+
+/** `console.warn` once per `key` per page load, and never in production. */
+export function warnMapOnce(key: string, message: string): void {
+  if (process.env.NODE_ENV === "production") return;
+  if (warned.has(key)) return;
+  warned.add(key);
+  console.warn(`[maps] ${message}`);
+}
+
+/** Test-only: forget which warnings have already fired. */
+export function resetMapWarnings(): void {
+  warned.clear();
+}