@gustkit/mapbox-web 0.2.0

package/src/GustKitMap.tsx

@@ -0,0 +1,540 @@
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import mapboxgl from "mapbox-gl";
+import { CanvasParticleField, type CanvasProjectionAdapter } from "@gustkit/client/particles/canvas";
+import {
+  Product,
+  hasColorField,
+  syncFieldSession,
+  vectorAt,
+  type FieldSessionRequest,
+  type GeoBounds,
+  type GustKitSource,
+} from "@gustkit/client";
+import { fieldToDataUrl } from "./fieldPng.js";
+import { paintArrowGrid, paintArrowSpots, sparseArrowSpots } from "./arrows.js";
+import { ensureMapStyles } from "./styles.js";
+
+const TRANSPARENT_PX =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=";
+const EMPTY_FC: GeoJSON.FeatureCollection = { type: "FeatureCollection", features: [] };
+const DEFAULT_STYLE = "mapbox://styles/mapbox/dark-v11";
+
+/**
+ * Basemap tints, 20% darker than the stock dark-v11 values.
+ *
+ * Counter-intuitive on a dark style, but we lighten LAND to #5b6474 so it reads
+ * under a translucent weather overlay — and dark-v11's borders sit at
+ * hsl(0 0% 38-41%), which is almost exactly that luminance, so they vanish into
+ * the landmass. Taking them down 20% restores the contrast the stock style gets
+ * from near-black land.
+ */
+const LAND_FILL = "#5b6474";
+const COASTLINE = "#434446"; // was #545558
+const ADMIN_0 = "hsl(0, 0%, 33%)"; // country borders, was 41%
+const ADMIN_1 = "hsl(0, 0%, 30%)"; // state/province borders, was 38%
+
+export interface GustKitMapLayers {
+  field?: boolean;
+  particles?: boolean;
+  isobars?: boolean;
+  arrows?: boolean;
+  centers?: boolean;
+}
+
+export interface GustKitMapHover {
+  lon: number;
+  lat: number;
+  x: number;
+  y: number;
+}
+
+/**
+ * Neighbour prefetch is a scroll-smoothness luxury: each extra valid time is a
+ * FULL extra field (12 packs / ~540KB at a basin-wide view). On a metered or slow
+ * link that competes with the first paint for the same pipe, so skip it there and
+ * let the visible step have the bandwidth to itself. Unknown link ⇒ prefetch, so
+ * desktop behaviour is unchanged.
+ */
+function prefetchIsWorthIt(): boolean {
+  const c = (navigator as { connection?: { saveData?: boolean; effectiveType?: string } }).connection;
+  if (!c) return true;
+  if (c.saveData) return false;
+  return !(c.effectiveType === "slow-2g" || c.effectiveType === "2g" || c.effectiveType === "3g");
+}
+
+export interface GustKitMapProps {
+  accessToken: string;
+  source: GustKitSource;
+  product: Product;
+  timeMs: number;
+  validTimes?: number[];
+  layers?: GustKitMapLayers;
+  opacity?: number;
+  center?: [number, number];
+  zoom?: number;
+  interactive?: boolean;
+  /** Field pad fraction. Live maps 0.5; locked postcards 0. */
+  pad?: number;
+  marginTiles?: number;
+  particleCount?: number;
+  particleColor?: string;
+  downsample?: number;
+  /** "grid" = live map; "sparse" = postcard (≤6 arrows). */
+  arrowMode?: "grid" | "sparse";
+  styleURL?: string;
+  className?: string;
+  children?: ReactNode;
+  /** Native Mapbox instance after style load — add boats, extra layers. */
+  onMap?: (map: mapboxgl.Map) => void;
+  onHover?: (info: GustKitMapHover | null) => void;
+  /**
+   * Press-and-hold on a point (mouse or touch). Fires once per gesture, and only
+   * if the pointer stayed put — a drag/pan is a map gesture, not a long press.
+   */
+  onLongPress?: (info: GustKitMapHover) => void;
+  /** Long-press duration in ms (default 450). */
+  longPressMs?: number;
+  onFieldReady?: (rasterMs: number, pixels: number) => void;
+}
+
+function mapBounds(map: mapboxgl.Map): GeoBounds {
+  const b = map.getBounds()!;
+  return { west: b.getWest(), south: b.getSouth(), east: b.getEast(), north: b.getNorth() };
+}
+
+function quadOf(b: GeoBounds): [[number, number], [number, number], [number, number], [number, number]] {
+  return [
+    [b.west, b.north],
+    [b.east, b.north],
+    [b.east, b.south],
+    [b.west, b.south],
+  ];
+}
+
+function canvasAdapter(map: mapboxgl.Map): CanvasProjectionAdapter {
+  return {
+    getBounds: () => mapBounds(map),
+    getSize: () => {
+      const el = map.getContainer();
+      return { width: el.clientWidth, height: el.clientHeight };
+    },
+    project: (lon, lat) => {
+      const p = map.project([lon, lat]);
+      return { x: p.x, y: p.y };
+    },
+    pxPerDeg: () => {
+      const c = map.getCenter();
+      const a = map.project([c.lng, c.lat]);
+      const d = map.project([c.lng + 1, c.lat]);
+      return Math.hypot(d.x - a.x, d.y - a.y) || 1;
+    },
+  };
+}
+
+/**
+ * Default Mapbox weather map (ADR-016). Owns the Mapbox instance, the weather
+ * stack (field under labels, coastline, particles, isobars, arrows, centers),
+ * and `loadView` on camera idle via {@link syncFieldSession}.
+ */
+export function GustKitMap({
+  accessToken,
+  source,
+  product,
+  timeMs,
+  validTimes,
+  layers = {},
+  opacity = 0.6,
+  center = [-55, 32],
+  zoom = 3,
+  interactive = true,
+  pad,
+  marginTiles,
+  particleCount = 1800,
+  particleColor = "rgba(255,255,255,0.7)",
+  downsample = 3,
+  arrowMode = "grid",
+  styleURL = DEFAULT_STYLE,
+  className,
+  children,
+  onMap,
+  onHover,
+  onLongPress,
+  longPressMs = 450,
+  onFieldReady,
+}: GustKitMapProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const mapRef = useRef<mapboxgl.Map | null>(null);
+  const fieldRef = useRef<CanvasParticleField | null>(null);
+  const arrowsCanvasRef = useRef<HTMLCanvasElement | null>(null);
+  const markersRef = useRef<mapboxgl.Marker[]>([]);
+  const [ready, setReady] = useState(false);
+  const propsRef = useRef({
+    source,
+    product,
+    timeMs,
+    validTimes,
+    layers,
+    opacity,
+    pad,
+    marginTiles,
+    downsample,
+    arrowMode,
+    particleCount,
+    onFieldReady,
+    onHover,
+    onLongPress,
+  });
+  propsRef.current = {
+    source,
+    product,
+    timeMs,
+    validTimes,
+    layers,
+    opacity,
+    pad,
+    marginTiles,
+    downsample,
+    arrowMode,
+    particleCount,
+    onFieldReady,
+    onHover,
+    onLongPress,
+  };
+
+  useEffect(() => {
+    ensureMapStyles();
+  }, []);
+
+  useEffect(() => {
+    if (!containerRef.current || !accessToken) return;
+    mapboxgl.accessToken = accessToken;
+    const map = new mapboxgl.Map({
+      container: containerRef.current,
+      style: styleURL,
+      center,
+      zoom,
+      interactive,
+      projection: "mercator",
+      attributionControl: false,
+      fadeDuration: interactive ? undefined : 0,
+    });
+    mapRef.current = map;
+
+    map.on("load", () => {
+      // Every one of these is best-effort: a caller can pass their own
+      // `styleURL`, and these ids are dark-v11's. A style without them keeps its
+      // own colours rather than throwing.
+      for (const [layer, prop, value] of [
+        ["land", "background-color", LAND_FILL],
+        ["admin-0-boundary", "line-color", ADMIN_0],
+        ["admin-1-boundary", "line-color", ADMIN_1],
+      ] as const) {
+        try {
+          map.setPaintProperty(layer, prop, value);
+        } catch {
+          /* style layer id differs */
+        }
+      }
+
+      /**
+       * Insert our overlays BELOW the whole admin group, not just below
+       * `admin-0-boundary`.
+       *
+       * dark-v11 orders admin layers as [admin-1-bg, admin-0-bg, admin-1,
+       * admin-0, admin-0-disputed], so anchoring to `admin-0-boundary` dropped
+       * the weather raster on top of `admin-1-boundary` — country borders
+       * survived and every state/province line was painted over. Anchoring to
+       * the FIRST admin layer keeps them all above the weather.
+       */
+      const adminAnchor = map.getStyle().layers?.find((l) => l.id.startsWith("admin"))?.id;
+      const b0 = mapBounds(map);
+      map.addSource("gk-field", { type: "image", url: TRANSPARENT_PX, coordinates: quadOf(b0) });
+      map.addLayer(
+        {
+          id: "gk-field",
+          type: "raster",
+          source: "gk-field",
+          paint: { "raster-opacity": propsRef.current.opacity, "raster-resampling": "linear", "raster-fade-duration": 0 },
+        },
+        adminAnchor,
+      );
+      map.addLayer(
+        {
+          id: "gk-coastline",
+          type: "line",
+          source: "composite",
+          "source-layer": "water",
+          layout: { "line-join": "round" },
+          paint: { "line-color": COASTLINE, "line-width": 1.4, "line-opacity": 0.9 },
+        },
+        adminAnchor,
+      );
+      map.addSource("gk-isobars", { type: "geojson", data: EMPTY_FC });
+      map.addLayer({
+        id: "gk-isobars",
+        type: "line",
+        source: "gk-isobars",
+        layout: { "line-join": "round", "line-cap": "round" },
+        paint: {
+          "line-color": ["case", ["get", "major"], "#ffffff", "#c3d4e8"],
+          "line-width": ["case", ["get", "major"], 1.3, 0.6],
+          "line-opacity": 0.7,
+        },
+      });
+
+      const cc = map.getCanvasContainer();
+      const arrows = document.createElement("canvas");
+      arrows.className = "gk-overlay gk-arrows";
+      cc.appendChild(arrows);
+      arrowsCanvasRef.current = arrows;
+
+      const particles = document.createElement("canvas");
+      particles.className = "gk-overlay gk-particles";
+      cc.appendChild(particles);
+      const field = new CanvasParticleField(particles, canvasAdapter(map), {
+        sample: source.vectorSampler(product) ?? (() => null),
+        color: particleColor,
+        count: particleCount,
+      });
+      fieldRef.current = field;
+      field.start();
+
+      map.on("movestart", () => {
+        field.moveStart();
+        clearArrows();
+      });
+      map.on("moveend", () => {
+        field.moveEnd();
+        refreshField();
+        drawArrows();
+      });
+      map.on("resize", () => {
+        field.resize();
+        refreshField();
+        drawArrows();
+      });
+      map.on("mousemove", (e) => {
+        propsRef.current.onHover?.({ lon: e.lngLat.lng, lat: e.lngLat.lat, x: e.point.x, y: e.point.y });
+      });
+      map.on("mouseout", () => propsRef.current.onHover?.(null));
+
+      // Press-and-hold → point query. Cancelled by movement beyond a slop radius
+      // (that is a pan), by release, or by the map starting to move/zoom, so it
+      // never fires mid-gesture. Touch and mouse share one path.
+      let pressTimer: ReturnType<typeof setTimeout> | null = null;
+      let pressStart: { x: number; y: number } | null = null;
+      const SLOP_PX = 8;
+      const cancelPress = () => {
+        if (pressTimer) clearTimeout(pressTimer);
+        pressTimer = null;
+        pressStart = null;
+      };
+      const beginPress = (e: mapboxgl.MapMouseEvent | mapboxgl.MapTouchEvent) => {
+        if (!propsRef.current.onLongPress) return;
+        cancelPress();
+        const { lng, lat } = e.lngLat;
+        const point = e.point;
+        pressStart = { x: point.x, y: point.y };
+        pressTimer = setTimeout(() => {
+          pressTimer = null;
+          pressStart = null;
+          propsRef.current.onLongPress?.({ lon: lng, lat, x: point.x, y: point.y });
+        }, longPressMs);
+      };
+      const movePress = (e: mapboxgl.MapMouseEvent | mapboxgl.MapTouchEvent) => {
+        if (!pressStart) return;
+        if (Math.hypot(e.point.x - pressStart.x, e.point.y - pressStart.y) > SLOP_PX) cancelPress();
+      };
+      map.on("mousedown", beginPress);
+      map.on("touchstart", beginPress);
+      map.on("mousemove", movePress);
+      map.on("touchmove", movePress);
+      for (const ev of ["mouseup", "touchend", "touchcancel", "dragstart", "movestart", "zoomstart"] as const) {
+        map.on(ev, cancelPress);
+      }
+      // Suppress the browser context menu so a touch long-press feels native.
+      map.getCanvas().addEventListener("contextmenu", (ev) => ev.preventDefault());
+
+      if (!interactive) {
+        const ro = new ResizeObserver(() => {
+          map.resize();
+          fieldRef.current?.resize();
+        });
+        ro.observe(map.getContainer());
+        (map as unknown as { _gkRo?: ResizeObserver })._gkRo = ro;
+      }
+
+      onMap?.(map);
+      setReady(true);
+      refreshField();
+      drawArrows();
+    });
+
+    return () => {
+      fieldRef.current?.destroy();
+      markersRef.current.forEach((m) => m.remove());
+      markersRef.current = [];
+      const ro = (map as unknown as { _gkRo?: ResizeObserver })._gkRo;
+      ro?.disconnect();
+      map.remove();
+      mapRef.current = null;
+    };
+    // Camera identity — remount when the locked place changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [accessToken, styleURL, center[0], center[1], zoom, interactive]);
+
+  function refreshField() {
+    const map = mapRef.current;
+    const p = propsRef.current;
+    if (!map || !map.getLayer("gk-field")) return;
+    const showField = (p.layers.field ?? true) && hasColorField(p.product);
+    map.setLayoutProperty("gk-field", "visibility", showField ? "visible" : "none");
+    const el = map.getContainer();
+    const w = el.clientWidth;
+    const h = el.clientHeight;
+    if (w < 2 || h < 2 || p.timeMs <= 0) return;
+    const bounds = mapBounds(map);
+    if (bounds.west === bounds.east || bounds.north <= bounds.south) return;
+    const z = map.getZoom();
+    const gen = ((map as unknown as { _gkFieldGen?: number })._gkFieldGen ?? 0) + 1;
+    (map as unknown as { _gkFieldGen?: number })._gkFieldGen = gen;
+    const apply = (session: Awaited<ReturnType<typeof syncFieldSession>>) => {
+      if (mapRef.current !== map) return;
+      if ((map as unknown as { _gkFieldGen?: number })._gkFieldGen !== gen) return;
+      if (showField) {
+        const t0 = performance.now();
+        const url = fieldToDataUrl(session.field);
+        p.onFieldReady?.(Math.round(performance.now() - t0), session.field.width * session.field.height);
+        const src = map.getSource("gk-field") as mapboxgl.ImageSource | undefined;
+        if (url && src) src.updateImage({ url, coordinates: quadOf(session.padded) });
+        map.setPaintProperty("gk-field", "raster-opacity", p.opacity);
+      }
+      drawArrows();
+    };
+    const req: FieldSessionRequest = {
+      source: p.source,
+      product: p.product,
+      timeMs: p.timeMs,
+      bounds,
+      zoom: z,
+      size: { width: w, height: h },
+      pad: p.pad,
+      downsample: p.downsample,
+      validTimes: p.validTimes,
+      prefetchDelayMs: 800,
+      prefetchNeighbours: prefetchIsWorthIt(),
+      viewOptions: p.marginTiles != null ? { marginTiles: p.marginTiles } : undefined,
+      onPartial: apply,
+    };
+    void syncFieldSession(req).then(apply);
+  }
+
+  function clearArrows() {
+    const c = arrowsCanvasRef.current;
+    if (!c) return;
+    c.getContext("2d")?.clearRect(0, 0, c.width, c.height);
+  }
+
+  function drawArrows() {
+    const map = mapRef.current;
+    const canvas = arrowsCanvasRef.current;
+    const p = propsRef.current;
+    if (!map || !canvas) return;
+    const el = map.getContainer();
+    const w = el.clientWidth;
+    const h = el.clientHeight;
+    const dpr = window.devicePixelRatio || 1;
+    canvas.width = Math.round(w * dpr);
+    canvas.height = Math.round(h * dpr);
+    canvas.style.width = `${w}px`;
+    canvas.style.height = `${h}px`;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return;
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    ctx.clearRect(0, 0, w, h);
+    if (!p.layers.arrows || p.product === Product.Pressure || w < 2) return;
+    if (p.arrowMode === "sparse") {
+      const magMax = p.product === Product.Wind ? 25 : 8;
+      const spots = sparseArrowSpots(w, h, (px, py) => {
+        const ll = map.unproject([px, py]);
+        return vectorAt(p.source, p.product, ll.lng, ll.lat);
+      });
+      paintArrowSpots(ctx, spots, magMax, 3);
+    } else {
+      paintArrowGrid(ctx, w, h, p.source, p.product, (px, py) => {
+        const ll = map.unproject([px, py]);
+        return { lon: ll.lng, lat: ll.lat };
+      });
+    }
+  }
+
+  useEffect(() => {
+    if (ready) refreshField();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ready, source, product, timeMs, opacity]);
+
+  useEffect(() => {
+    if (ready) drawArrows();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ready, layers.arrows, product, arrowMode]);
+
+  useEffect(() => {
+    const field = fieldRef.current;
+    if (!ready || !field) return;
+    field.setSampler(source.vectorSampler(product) ?? (() => null));
+    field.setEnabled((layers.particles ?? true) && product !== Product.Pressure);
+  }, [ready, source, product, timeMs, layers.particles]);
+
+  useEffect(() => {
+    const map = mapRef.current;
+    if (!ready || !map || !map.getLayer("gk-isobars")) return;
+    const on = layers.isobars ?? false;
+    map.setLayoutProperty("gk-isobars", "visibility", on ? "visible" : "none");
+    if (!on) return;
+    let cancelled = false;
+    void source.fetchIsobars(timeMs).then((gj) => {
+      if (cancelled) return;
+      const src = map.getSource("gk-isobars") as mapboxgl.GeoJSONSource | undefined;
+      src?.setData(gj ?? EMPTY_FC);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [ready, source, timeMs, layers.isobars]);
+
+  useEffect(() => {
+    const map = mapRef.current;
+    if (!ready || !map) return;
+    markersRef.current.forEach((m) => m.remove());
+    markersRef.current = [];
+    if (!layers.centers) return;
+    let cancelled = false;
+    void source.fetchCenters(timeMs).then((centers) => {
+      if (cancelled) return;
+      for (const c of centers) {
+        const el = document.createElement("div");
+        el.className = `gk-center gk-center-${c.kind === "H" ? "high" : "low"}`;
+        el.innerHTML = `<b>${c.kind}</b><span>${Math.round(c.pressureHpa)}</span>`;
+        markersRef.current.push(new mapboxgl.Marker({ element: el }).setLngLat([c.lon, c.lat]).addTo(map));
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [ready, source, timeMs, layers.centers]);
+
+  if (!accessToken) {
+    return (
+      <div className="gk-notoken">
+        Set a Mapbox public token (<code>pk.…</code>) to load the map.
+      </div>
+    );
+  }
+
+  return (
+    <div className={className ?? "gk-map-root"} style={{ position: "absolute", inset: 0 }}>
+      <div ref={containerRef} className="gk-map-canvas" />
+      {children ? <div className="gk-map-chrome">{children}</div> : null}
+    </div>
+  );
+}

package/src/arrows.ts

@@ -0,0 +1,112 @@
+import { vectorAt, type GustKitSource, type VectorSample } from "@gustkit/client";
+import { Product } from "@gustkit/client";
+
+export interface ArrowSpot {
+  x: number;
+  y: number;
+  dirU: number;
+  dirV: number;
+  mag: number;
+}
+
+/** 3×2 sample grid, inset from the postcard edges — at most `maxCount` arrows. */
+export function sparseArrowSpots(
+  w: number,
+  h: number,
+  sample: (px: number, py: number) => VectorSample | null,
+  maxCount = 6,
+): ArrowSpot[] {
+  const cols = 3;
+  const rows = 2;
+  const insetX = w * 0.22;
+  const insetY = h * 0.28;
+  const spanX = cols > 1 ? (w - 2 * insetX) / (cols - 1) : 0;
+  const spanY = rows > 1 ? (h - 2 * insetY) / (rows - 1) : 0;
+  const out: ArrowSpot[] = [];
+  for (let r = 0; r < rows && out.length < maxCount; r++) {
+    for (let c = 0; c < cols && out.length < maxCount; c++) {
+      const x = insetX + c * spanX;
+      const y = insetY + r * spanY;
+      const v = sample(x, y);
+      if (!v || !(v.mag > 0)) continue;
+      out.push({ x, y, dirU: v.dirU, dirV: v.dirV, mag: v.mag });
+    }
+  }
+  return out;
+}
+
+export function paintArrowSpots(
+  ctx: CanvasRenderingContext2D,
+  spots: ArrowSpot[],
+  magMax: number,
+  scale = 1,
+): void {
+  const color = "rgba(255,255,255,0.92)";
+  const stroke = Math.max(1.4, 1.5 * Math.sqrt(scale));
+  ctx.strokeStyle = color;
+  ctx.fillStyle = color;
+  ctx.lineWidth = stroke;
+  ctx.lineCap = "round";
+  ctx.lineJoin = "miter";
+  ctx.shadowColor = "rgba(0,0,0,0.55)";
+  ctx.shadowBlur = 2 * Math.sqrt(scale);
+  for (const s of spots) {
+    const len = (8 + Math.min(s.mag / magMax, 1) * 16) * scale;
+    const ang = Math.atan2(-s.dirV, s.dirU);
+    const hl = Math.min(len * 0.45, 7 * scale);
+    const hw = hl * 0.7;
+    const shaft = Math.max(stroke, len - hl);
+    const bx = s.x + Math.cos(ang) * shaft;
+    const by = s.y + Math.sin(ang) * shaft;
+    const ex = s.x + Math.cos(ang) * len;
+    const ey = s.y + Math.sin(ang) * len;
+    ctx.beginPath();
+    ctx.moveTo(s.x, s.y);
+    ctx.lineTo(bx, by);
+    ctx.stroke();
+    ctx.beginPath();
+    ctx.moveTo(ex, ey);
+    ctx.lineTo(bx + Math.sin(ang) * hw, by - Math.cos(ang) * hw);
+    ctx.lineTo(bx - Math.sin(ang) * hw, by + Math.cos(ang) * hw);
+    ctx.closePath();
+    ctx.fill();
+  }
+  ctx.shadowBlur = 0;
+}
+
+export function paintArrowGrid(
+  ctx: CanvasRenderingContext2D,
+  w: number,
+  h: number,
+  source: GustKitSource,
+  product: Product,
+  unproject: (px: number, py: number) => { lon: number; lat: number },
+): void {
+  const magMax = product === Product.Wind ? 25 : 8;
+  const step = 46;
+  ctx.strokeStyle = "rgba(255,255,255,0.9)";
+  ctx.lineWidth = 1.3;
+  ctx.lineCap = "round";
+  ctx.shadowColor = "rgba(0,0,0,0.55)";
+  ctx.shadowBlur = 2;
+  for (let py = step / 2; py < h; py += step) {
+    for (let px = step / 2; px < w; px += step) {
+      const ll = unproject(px, py);
+      const v = vectorAt(source, product, ll.lon, ll.lat);
+      if (!v || !(v.mag > 0)) continue;
+      const len = 6 + Math.min(v.mag / magMax, 1) * 16;
+      const ex = px + v.dirU * len;
+      const ey = py - v.dirV * len;
+      ctx.beginPath();
+      ctx.moveTo(px, py);
+      ctx.lineTo(ex, ey);
+      const ang = Math.atan2(ey - py, ex - px);
+      const hl = 4;
+      ctx.lineTo(ex - hl * Math.cos(ang - 0.5), ey - hl * Math.sin(ang - 0.5));
+      ctx.moveTo(ex, ey);
+      ctx.lineTo(ex - hl * Math.cos(ang + 0.5), ey - hl * Math.sin(ang + 0.5));
+      ctx.stroke();
+    }
+  }
+  ctx.shadowBlur = 0;
+}

package/src/fieldPng.ts

@@ -0,0 +1,14 @@
+import type { RasterField } from "@gustkit/client";
+
+/** Encode an RGBA field as a PNG data URL for a Mapbox ImageSource. */
+export function fieldToDataUrl(field: RasterField): string | null {
+  if (field.width < 1 || field.height < 1 || field.rgba.length === 0) return null;
+  const canvas = document.createElement("canvas");
+  canvas.width = field.width;
+  canvas.height = field.height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return null;
+  const img = new ImageData(new Uint8ClampedArray(field.rgba), field.width, field.height);
+  ctx.putImageData(img, 0, 0);
+  return canvas.toDataURL("image/png");
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { GustKitMap } from "./GustKitMap.js";
+export type { GustKitMapProps, GustKitMapLayers, GustKitMapHover } from "./GustKitMap.js";

package/src/styles.ts

@@ -0,0 +1,25 @@
+const CSS = `
+.gk-map-root{position:relative;width:100%;height:100%}
+.gk-map-canvas{position:absolute;inset:0}
+.gk-overlay{position:absolute;top:0;left:0;pointer-events:none}
+.gk-arrows{z-index:1}
+.gk-particles{z-index:2}
+.gk-map-chrome{position:absolute;inset:0;pointer-events:none;z-index:3}
+.gk-center{display:flex;flex-direction:column;align-items:center;line-height:1;pointer-events:none;text-shadow:0 1px 2px rgba(0,0,0,.7);font-variant-numeric:tabular-nums}
+.gk-center b{font-size:18px;font-weight:800}
+.gk-center span{font-size:10px;color:#e5e7eb}
+.gk-center-high b{color:#4a86e8}
+.gk-center-low b{color:#e2555a}
+.gk-notoken{display:flex;align-items:center;justify-content:center;color:#94a3b8;padding:24px;text-align:center}
+`;
+
+let injected = false;
+
+export function ensureMapStyles(): void {
+  if (injected || typeof document === "undefined") return;
+  injected = true;
+  const el = document.createElement("style");
+  el.dataset.gustkit = "mapbox-web";
+  el.textContent = CSS;
+  document.head.appendChild(el);
+}