@mapmap/maps 0.1.0 → 0.3.0

package/dist/index.js

@@ -3,6 +3,456 @@ import { Protocol } from 'pmtiles';
 
 // src/map.ts
 
+// src/diagnostics.ts
+var DOCS = "https://mapmap.ai/docs";
+var reported = /* @__PURE__ */ new Set();
+var MAPLIBRE_REGISTRY_KEY = /* @__PURE__ */ Symbol.for("mapmap.maplibre-instances");
+function resetDiagnostics() {
+  reported.clear();
+  const holder = globalThis;
+  delete holder[MAPLIBRE_REGISTRY_KEY];
+}
+function report(issue, message) {
+  if (reported.has(issue)) return;
+  reported.add(issue);
+  console.error(`MapMap [${issue}]: ${message}`);
+}
+function runMapDiagnostics(input) {
+  checkDuplicateMaplibre(input.maplibre);
+  checkWebgl();
+  checkContainer(input.container);
+  watchForAuthFailures(input.map, input.apiKey);
+}
+function checkContainer(container) {
+  if (container === void 0 || typeof document === "undefined") return;
+  let element;
+  try {
+    element = typeof container === "string" ? document.getElementById(container) : container;
+  } catch {
+    return;
+  }
+  if (!element) return;
+  if (typeof element.isConnected !== "boolean") return;
+  if (!element.isConnected) {
+    report(
+      "container-detached",
+      `the map container element is not attached to the DOM, so nothing can render. Append it to the document before constructing the map. ${DOCS}#container`
+    );
+    return;
+  }
+  if (element.clientHeight === 0) {
+    report(
+      "container-zero-height",
+      `the map container's height is 0px, so MapLibre is rendering into an invisible canvas (no error, no map). Give it a real height, e.g. #map { height: 100vh; }. If the height arrives later (CSS load, layout), you can ignore this. ${DOCS}#container-height`
+    );
+  }
+}
+function checkDuplicateMaplibre(maplibre) {
+  if (typeof maplibre !== "object" && typeof maplibre !== "function") return;
+  if (maplibre === null) return;
+  const holder = globalThis;
+  const registry = holder[MAPLIBRE_REGISTRY_KEY] ??= /* @__PURE__ */ new Set();
+  registry.add(maplibre);
+  const windowCopy = globalThis.maplibregl;
+  if (windowCopy !== void 0 && (typeof windowCopy === "object" || typeof windowCopy === "function")) {
+    registry.add(windowCopy);
+  }
+  if (registry.size > 1) {
+    report(
+      "duplicate-maplibre",
+      `two different maplibre-gl instances are loaded on this page (duplicate dependency, a CDN <script> next to the bundled copy, or micro-frontends). Maps, styles and the pmtiles protocol registration will not be shared between them. De-duplicate so the app owns a single maplibre-gl - it is a peerDependency of @mapmap/maps for exactly this reason. ${DOCS}#duplicate-maplibre`
+    );
+  }
+}
+function checkWebgl() {
+  if (typeof document === "undefined") return;
+  try {
+    const canvas = document.createElement("canvas");
+    const gl = canvas.getContext("webgl2") ?? canvas.getContext("webgl");
+    if (!gl) {
+      report(
+        "webgl-unavailable",
+        `this browser/environment reports no WebGL support, so the map cannot render. Common causes: headless browsers without --use-gl, blocked GPU/hardware acceleration, remote desktops. ${DOCS}#webgl`
+      );
+    }
+  } catch {
+  }
+}
+function watchForAuthFailures(map, apiKey) {
+  const on = map?.on;
+  if (typeof on !== "function" || map === null || map === void 0) return;
+  try {
+    on.call(map, "error", (ev) => {
+      const status = ev?.error?.status;
+      const message = ev?.error?.message ?? "";
+      const unauthorised = status === 401 || /unauthori[sz]ed/i.test(message);
+      if (!unauthorised) return;
+      report(
+        "invalid-api-key",
+        apiKey ? `the gateway rejected your API key (HTTP 401). Check the \`apiKey\` for typos or revocation - keys look like "snk_\u2026". ${DOCS}#authentication` : `a request was rejected with HTTP 401 and no \`apiKey\` was configured. Pass one to the map (\`new MapMapMap({ apiKey: "snk_\u2026" })\`) - issue a free key with POST https://api.mapmap.ai/v1/keys. ${DOCS}#authentication`
+      );
+    });
+  } catch {
+  }
+}
+
+// src/coords.ts
+function toLngLat(point) {
+  if (Array.isArray(point)) {
+    const [lng2, lat2] = point;
+    assertFinite(lng2, lat2);
+    return [lng2, lat2];
+  }
+  const lng = "lng" in point ? point.lng : point.lon;
+  const lat = point.lat;
+  assertFinite(lng, lat);
+  return [lng, lat];
+}
+function formatCoord(point) {
+  const [lng, lat] = toLngLat(point);
+  return `${lng},${lat}`;
+}
+function formatCoords(points) {
+  if (points.length < 2) {
+    throw new Error("at least two coordinates are required for a route");
+  }
+  return points.map(formatCoord).join(";");
+}
+function unwrapLngs(coordinates) {
+  const out = [];
+  for (const [lng, lat] of coordinates) {
+    const prev = out[out.length - 1];
+    let unwrapped = lng;
+    if (prev) {
+      while (unwrapped - prev[0] > 180) unwrapped -= 360;
+      while (unwrapped - prev[0] < -180) unwrapped += 360;
+    }
+    out.push([unwrapped, lat]);
+  }
+  return out;
+}
+function assertFinite(lng, lat) {
+  if (!Number.isFinite(lng) || !Number.isFinite(lat)) {
+    throw new Error(`invalid coordinate: lng=${lng}, lat=${lat}`);
+  }
+  if (lng < -180 || lng > 180 || lat < -90 || lat > 90) {
+    throw new Error(
+      `coordinate out of range: lng=${lng} (\xB1180), lat=${lat} (\xB190) - check lng/lat order`
+    );
+  }
+}
+
+// src/effects.ts
+var FLOW_COLOUR = "#3a86ff";
+var EARTH_RADIUS_M = 63710088e-1;
+function haversineM(a, b) {
+  const rad = (deg) => deg * Math.PI / 180;
+  const dLat = rad(b[1] - a[1]);
+  const dLon = rad(b[0] - a[0]);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(rad(a[1])) * Math.cos(rad(b[1])) * Math.sin(dLon / 2) ** 2;
+  return 2 * EARTH_RADIUS_M * Math.asin(Math.sqrt(h));
+}
+var RIBBON_FLOATS_PER_VERTEX = 5;
+function lngLatToMercator(lngLat) {
+  const [lng, lat] = lngLat;
+  const x = (lng + 180) / 360;
+  const y = (1 - Math.log(Math.tan(Math.PI / 4 + lat * Math.PI / 360)) / Math.PI) / 2;
+  return [x, y];
+}
+function tessellateRouteRibbon(coordinates) {
+  const points = [];
+  for (const lngLat of unwrapLngs(coordinates)) {
+    const p = lngLatToMercator(lngLat);
+    const last = points[points.length - 1];
+    if (!last || last[0] !== p[0] || last[1] !== p[1]) points.push(p);
+  }
+  if (points.length < 2) {
+    return { vertices: new Float32Array(0), vertexCount: 0 };
+  }
+  const cumulative = [0];
+  for (let i = 1; i < points.length; i++) {
+    const dx = points[i][0] - points[i - 1][0];
+    const dy = points[i][1] - points[i - 1][1];
+    cumulative.push(cumulative[i - 1] + Math.hypot(dx, dy));
+  }
+  const total = cumulative[cumulative.length - 1];
+  const vertices = new Float32Array(
+    points.length * 2 * RIBBON_FLOATS_PER_VERTEX
+  );
+  let out = 0;
+  for (let i = 0; i < points.length; i++) {
+    const prev = points[i - 1];
+    const here = points[i];
+    const next = points[i + 1];
+    let dirX = 0;
+    let dirY = 0;
+    if (prev) {
+      const len = Math.hypot(here[0] - prev[0], here[1] - prev[1]);
+      dirX += (here[0] - prev[0]) / len;
+      dirY += (here[1] - prev[1]) / len;
+    }
+    if (next) {
+      const len = Math.hypot(next[0] - here[0], next[1] - here[1]);
+      dirX += (next[0] - here[0]) / len;
+      dirY += (next[1] - here[1]) / len;
+    }
+    const dirLen = Math.hypot(dirX, dirY);
+    if (dirLen < 1e-12 && prev) {
+      const len = Math.hypot(here[0] - prev[0], here[1] - prev[1]);
+      dirX = (here[0] - prev[0]) / len;
+      dirY = (here[1] - prev[1]) / len;
+    } else {
+      dirX /= dirLen;
+      dirY /= dirLen;
+    }
+    const nx = -dirY;
+    const ny = dirX;
+    const progress = total > 0 ? cumulative[i] / total : 0;
+    for (const side of [1, -1]) {
+      vertices[out++] = here[0];
+      vertices[out++] = here[1];
+      vertices[out++] = nx * side;
+      vertices[out++] = ny * side;
+      vertices[out++] = progress;
+    }
+  }
+  return { vertices, vertexCount: points.length * 2 };
+}
+function parseCssColour(colour2) {
+  const v = colour2.trim();
+  if (v.startsWith("#")) {
+    const hex = v.slice(1);
+    if (!/^[0-9a-fA-F]+$/.test(hex)) return void 0;
+    if (hex.length === 3 || hex.length === 4) {
+      const parts = hex.split("").map((c) => parseInt(c + c, 16) / 255);
+      const [r, g, b, a] = parts;
+      if (r === void 0 || g === void 0 || b === void 0) return void 0;
+      return [r, g, b, a ?? 1];
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      const chan = (i) => parseInt(hex.slice(i, i + 2), 16) / 255;
+      return [chan(0), chan(2), chan(4), hex.length === 8 ? chan(6) : 1];
+    }
+    return void 0;
+  }
+  const fn = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/.exec(v);
+  if (fn) {
+    const r = Number(fn[1]) / 255;
+    const g = Number(fn[2]) / 255;
+    const b = Number(fn[3]) / 255;
+    const a = fn[4] !== void 0 ? Number(fn[4]) : 1;
+    if ([r, g, b, a].some((c) => !Number.isFinite(c) || c < 0 || c > 1)) {
+      return void 0;
+    }
+    return [r, g, b, a];
+  }
+  return void 0;
+}
+function prefersReducedMotion() {
+  if (typeof matchMedia !== "function") return false;
+  try {
+    return matchMedia("(prefers-reduced-motion: reduce)").matches;
+  } catch {
+    return false;
+  }
+}
+var VERTEX_SHADER = `
+uniform mat4 u_matrix;
+uniform float u_half_width;
+attribute vec2 a_pos;
+attribute vec2 a_normal;
+attribute float a_progress;
+varying float v_progress;
+void main() {
+  v_progress = a_progress;
+  gl_Position = u_matrix * vec4(a_pos + a_normal * u_half_width, 0.0, 1.0);
+}
+`;
+var FRAGMENT_SHADER = `
+precision mediump float;
+uniform vec4 u_color;
+uniform float u_phase;
+uniform float u_repeats;
+varying float v_progress;
+void main() {
+  float t = fract(v_progress * u_repeats - u_phase);
+  // A soft comet: rises quickly, decays slowly, never fully dark so the
+  // ribbon always traces the route.
+  float pulse = smoothstep(0.0, 0.25, t) * (1.0 - smoothstep(0.35, 1.0, t));
+  float energy = 0.25 + 0.75 * pulse;
+  float alpha = u_color.a * energy;
+  // Premultiplied alpha, matching MapLibre's framebuffer convention.
+  gl_FragColor = vec4(u_color.rgb * alpha, alpha);
+}
+`;
+var warnedWebglFailure = false;
+var FLOW_DEFAULTS = {
+  color: FLOW_COLOUR,
+  width: 10,
+  speed: 0.6
+};
+function mercatorUnitsPerPixel(zoom) {
+  return 1 / (512 * 2 ** zoom);
+}
+function routeLengthM(coordinates) {
+  let length = 0;
+  for (let i = 1; i < coordinates.length; i++) {
+    length += haversineM(coordinates[i - 1], coordinates[i]);
+  }
+  return length;
+}
+var FlowRouteEffectLayer = class {
+  constructor(geometry, options = {}) {
+    this.type = "custom";
+    this.renderingMode = "2d";
+    this.program = null;
+    this.buffer = null;
+    this.vertexCount = 0;
+    this.repeats = 8;
+    this.startedAt = 0;
+    this.failed = false;
+    this.aPos = 0;
+    this.aNormal = 0;
+    this.aProgress = 0;
+    this.uMatrix = null;
+    this.uHalfWidth = null;
+    this.uColor = null;
+    this.uPhase = null;
+    this.uRepeats = null;
+    this.id = options.id ?? "mapmap-route-effect";
+    this.geometry = geometry;
+    this.colour = (options.color !== void 0 ? parseCssColour(options.color) : void 0) ?? parseCssColour(FLOW_DEFAULTS.color);
+    this.widthPx = options.width ?? FLOW_DEFAULTS.width;
+    this.speed = options.speed ?? FLOW_DEFAULTS.speed;
+    this.animate = !prefersReducedMotion();
+  }
+  /** Swap the ribbon onto a new route line (e.g. after a reroute). */
+  setGeometry(geometry) {
+    this.geometry = geometry;
+    if (this.glRef && !this.failed) this.upload(this.glRef);
+    this.mapRef?.triggerRepaint();
+  }
+  onAdd(map, gl) {
+    this.mapRef = map;
+    this.glRef = gl;
+    this.startedAt = now();
+    try {
+      const program = gl.createProgram();
+      if (!program) throw new Error("createProgram returned null");
+      for (const [kind, source] of [
+        [gl.VERTEX_SHADER, VERTEX_SHADER],
+        [gl.FRAGMENT_SHADER, FRAGMENT_SHADER]
+      ]) {
+        const shader = gl.createShader(kind);
+        if (!shader) throw new Error("createShader returned null");
+        gl.shaderSource(shader, source);
+        gl.compileShader(shader);
+        if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+          throw new Error(gl.getShaderInfoLog(shader) ?? "shader compile failed");
+        }
+        gl.attachShader(program, shader);
+      }
+      gl.linkProgram(program);
+      if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        throw new Error(gl.getProgramInfoLog(program) ?? "program link failed");
+      }
+      this.program = program;
+      this.aPos = gl.getAttribLocation(program, "a_pos");
+      this.aNormal = gl.getAttribLocation(program, "a_normal");
+      this.aProgress = gl.getAttribLocation(program, "a_progress");
+      this.uMatrix = gl.getUniformLocation(program, "u_matrix");
+      this.uHalfWidth = gl.getUniformLocation(program, "u_half_width");
+      this.uColor = gl.getUniformLocation(program, "u_color");
+      this.uPhase = gl.getUniformLocation(program, "u_phase");
+      this.uRepeats = gl.getUniformLocation(program, "u_repeats");
+      this.upload(gl);
+    } catch (error) {
+      this.failed = true;
+      if (!warnedWebglFailure) {
+        warnedWebglFailure = true;
+        console.warn(
+          `MapMap: route effect "flow" disabled (WebGL setup failed: ${error instanceof Error ? error.message : String(error)}). Falling back to the plain route line.`
+        );
+      }
+    }
+  }
+  onRemove(_map, gl) {
+    if (this.buffer) gl.deleteBuffer(this.buffer);
+    if (this.program) gl.deleteProgram(this.program);
+    this.buffer = null;
+    this.program = null;
+    this.mapRef = void 0;
+    this.glRef = void 0;
+  }
+  render(gl, args) {
+    if (this.failed || !this.program || !this.buffer || this.vertexCount < 3) {
+      return;
+    }
+    const matrix = projectionMatrixOf(args);
+    if (!matrix || !this.mapRef) return;
+    gl.useProgram(this.program);
+    gl.uniformMatrix4fv(this.uMatrix, false, matrix);
+    const halfWidth = this.widthPx / 2 * mercatorUnitsPerPixel(this.mapRef.getZoom());
+    gl.uniform1f(this.uHalfWidth, halfWidth);
+    gl.uniform4f(this.uColor, ...this.colour);
+    const phase = this.animate ? (now() - this.startedAt) / 1e3 * this.speed % 1 : 0;
+    gl.uniform1f(this.uPhase, phase);
+    gl.uniform1f(this.uRepeats, this.repeats);
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+    const stride = RIBBON_FLOATS_PER_VERTEX * 4;
+    gl.enableVertexAttribArray(this.aPos);
+    gl.vertexAttribPointer(this.aPos, 2, gl.FLOAT, false, stride, 0);
+    gl.enableVertexAttribArray(this.aNormal);
+    gl.vertexAttribPointer(this.aNormal, 2, gl.FLOAT, false, stride, 8);
+    gl.enableVertexAttribArray(this.aProgress);
+    gl.vertexAttribPointer(this.aProgress, 1, gl.FLOAT, false, stride, 16);
+    gl.enable(gl.BLEND);
+    gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+    gl.drawArrays(gl.TRIANGLE_STRIP, 0, this.vertexCount);
+    if (this.animate) this.mapRef.triggerRepaint();
+  }
+  upload(gl) {
+    const mesh = tessellateRouteRibbon(this.geometry.coordinates);
+    this.vertexCount = mesh.vertexCount;
+    this.repeats = Math.min(
+      80,
+      Math.max(2, Math.round(routeLengthM(this.geometry.coordinates) / 500))
+    );
+    if (!this.buffer) this.buffer = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.buffer);
+    gl.bufferData(gl.ARRAY_BUFFER, mesh.vertices, gl.STATIC_DRAW);
+  }
+};
+function now() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function projectionMatrixOf(args) {
+  if (Array.isArray(args)) return args;
+  if (args instanceof Float32Array || args instanceof Float64Array) {
+    return args instanceof Float64Array ? new Float32Array(args) : args;
+  }
+  if (typeof args === "object" && args !== null) {
+    const data = args.defaultProjectionData;
+    const main = data?.mainMatrix;
+    if (Array.isArray(main)) return main;
+    if (main instanceof Float32Array) return main;
+    if (main instanceof Float64Array) return new Float32Array(main);
+  }
+  return void 0;
+}
+var ROUTE_EFFECTS = {
+  flow: (geometry, options) => new FlowRouteEffectLayer(geometry, options)
+};
+function createRouteEffect(name, geometry, options) {
+  const factory = ROUTE_EFFECTS[name];
+  if (!factory) {
+    throw new Error(
+      `unknown route effect ${JSON.stringify(name)}; accepted effects: ` + Object.keys(ROUTE_EFFECTS).join(", ")
+    );
+  }
+  return factory(geometry, options);
+}
+
 // src/logo.ts
 var LOGO_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="84" height="20" viewBox="0 0 156 37" fill="none" role="img" aria-label="MapMap"><g stroke="#ffffff" stroke-linejoin="round" stroke-linecap="round"><path d="M146.965 19.2363C146.965 17.5281 146.64 16.2469 145.989 15.3927C145.358 14.5386 144.464 14.1115 143.304 14.1115C142.227 14.1115 141.352 14.5589 140.681 15.4537C140.03 16.3282 139.705 17.5382 139.705 19.0838V19.3889C139.705 20.9751 140.03 22.2055 140.681 23.08C141.352 23.9341 142.227 24.3612 143.304 24.3612C144.382 24.3612 145.257 23.924 145.928 23.0495C146.619 22.1547 146.965 20.8836 146.965 19.2363ZM150.778 19.2363C150.778 21.8598 150.188 23.8934 149.009 25.3373C147.85 26.7609 146.324 27.4727 144.433 27.4727C142.481 27.4727 140.925 26.7304 139.766 25.2458H139.705V33.8787H135.739V11.305H139.461L139.522 13.5319H139.583C140.803 11.844 142.42 11 144.433 11C146.406 11 147.951 11.7016 149.07 13.1048C150.209 14.5081 150.778 16.5519 150.778 19.2363Z" fill="#ffffff" stroke-width="3" paint-order="stroke"/><path d="M126.399 11C128.819 11 130.558 11.4779 131.615 12.4337C132.673 13.3692 133.202 14.8945 133.202 17.0095V22.8969C133.202 24.3409 133.354 25.7644 133.659 27.1676H129.907C129.785 26.4965 129.694 25.7136 129.633 24.8188H129.572C129.002 25.6526 128.229 26.3033 127.253 26.7711C126.297 27.2388 125.25 27.4727 124.111 27.4727C122.627 27.4727 121.437 27.066 120.542 26.2525C119.668 25.4187 119.23 24.2697 119.23 22.8054C119.23 21.0361 119.973 19.6227 121.457 18.5652C122.962 17.4874 125.118 16.9485 127.924 16.9485H129.236V16.857C129.236 15.7791 129.023 15.0267 128.596 14.5996C128.168 14.1725 127.406 13.959 126.308 13.959C124.315 13.959 122.433 14.4166 120.664 15.3317L120.085 12.3727C122.017 11.4576 124.121 11 126.399 11ZM122.952 22.5004C122.952 23.1512 123.145 23.6596 123.532 24.0256C123.918 24.3917 124.447 24.5747 125.118 24.5747C126.277 24.5747 127.253 24.1985 128.046 23.446C128.84 22.6936 129.236 21.7479 129.236 20.6091V19.5719H127.924C126.318 19.5719 125.087 19.8464 124.233 20.3955C123.379 20.9243 122.952 21.6259 122.952 22.5004Z" fill="#ffffff" stroke-width="3" paint-order="stroke"/><path d="M96.1152 11.305H99.7758L99.8673 13.4404H99.9284C101.108 11.8135 102.46 11 103.986 11C104.982 11 105.806 11.2034 106.456 11.6101C107.107 12.0168 107.666 12.6778 108.134 13.5929H108.195C109.517 11.8643 111.073 11 112.862 11C114.571 11 115.811 11.4779 116.584 12.4337C117.377 13.3692 117.774 14.9555 117.774 17.1925V27.1676H113.93V18.1077C113.93 16.5214 113.757 15.4537 113.412 14.9046C113.086 14.3555 112.496 14.081 111.642 14.081C110.91 14.081 110.27 14.4674 109.72 15.2402C109.171 16.013 108.897 16.9688 108.897 18.1077V27.1676H105.053V18.1077C105.053 16.5214 104.88 15.4537 104.535 14.9046C104.209 14.3555 103.619 14.081 102.765 14.081C102.033 14.081 101.393 14.4674 100.844 15.2402C100.294 16.013 100.02 16.9688 100.02 18.1077V27.1676H96.1152V11.305Z" fill="#ffffff" stroke-width="3" paint-order="stroke"/><path d="M90.8503 19.2363C90.8503 17.5281 90.525 16.2469 89.8742 15.3927C89.2438 14.5386 88.3489 14.1115 87.1898 14.1115C86.1119 14.1115 85.2374 14.5589 84.5663 15.4537C83.9155 16.3282 83.5902 17.5382 83.5902 19.0838V19.3889C83.5902 20.9751 83.9155 22.2055 84.5663 23.08C85.2374 23.9341 86.1119 24.3612 87.1898 24.3612C88.2676 24.3612 89.1421 23.924 89.8132 23.0495C90.5046 22.1547 90.8503 20.8836 90.8503 19.2363ZM94.6635 19.2363C94.6635 21.8598 94.0737 23.8934 92.8942 25.3373C91.735 26.7609 90.2097 27.4727 88.3184 27.4727C86.3661 27.4727 84.8104 26.7304 83.6512 25.2458H83.5902V33.8787H79.6245V11.305H83.3461L83.4071 13.5319H83.4681C84.6883 11.844 86.3051 11 88.3184 11C90.2911 11 91.8367 11.7016 92.9552 13.1048C94.094 14.5081 94.6635 16.5519 94.6635 19.2363Z" fill="#ffffff" stroke-width="3" paint-order="stroke"/><path d="M70.2844 11C72.7045 11 74.4432 11.4779 75.5008 12.4337C76.5583 13.3692 77.087 14.8945 77.087 17.0095V22.8969C77.087 24.3409 77.2395 25.7644 77.5446 27.1676H73.7925C73.6705 26.4965 73.5789 25.7136 73.5179 24.8188H73.4569C72.8875 25.6526 72.1147 26.3033 71.1385 26.7711C70.1827 27.2388 69.1354 27.4727 67.9965 27.4727C66.5119 27.4727 65.3223 27.066 64.4274 26.2525C63.553 25.4187 63.1157 24.2697 63.1157 22.8054C63.1157 21.0361 63.858 19.6227 65.3426 18.5652C66.8475 17.4874 69.0032 16.9485 71.8096 16.9485H73.1214V16.857C73.1214 15.7791 72.9078 15.0267 72.4808 14.5996C72.0537 14.1725 71.2911 13.959 70.1929 13.959C68.1999 13.959 66.3187 14.4166 64.5495 15.3317L63.9699 12.3727C65.9018 11.4576 68.0067 11 70.2844 11ZM66.8373 22.5004C66.8373 23.1512 67.0305 23.6596 67.4169 24.0256C67.8033 24.3917 68.3321 24.5747 69.0032 24.5747C70.1624 24.5747 71.1385 24.1985 71.9317 23.446C72.7248 22.6936 73.1214 21.7479 73.1214 20.6091V19.5719H71.8096C70.203 19.5719 68.9727 19.8464 68.1185 20.3955C67.2644 20.9243 66.8373 21.6259 66.8373 22.5004Z" fill="#ffffff" stroke-width="3" paint-order="stroke"/><path d="M40 11.3049H43.6606L43.7521 13.4403H43.8131C44.9927 11.8133 46.345 10.9999 47.8703 10.9999C48.8668 10.9999 49.6904 11.2032 50.3412 11.61C50.992 12.0167 51.5512 12.6777 52.019 13.5928H52.08C53.4019 11.8642 54.9576 10.9999 56.7472 10.9999C58.4555 10.9999 59.6961 11.4778 60.4689 12.4336C61.262 13.3691 61.6586 14.9554 61.6586 17.1924V27.1675H57.8149V18.1075C57.8149 16.5213 57.6421 15.4536 57.2963 14.9045C56.9709 14.3554 56.3812 14.0809 55.527 14.0809C54.7949 14.0809 54.1543 14.4673 53.6052 15.2401C53.0561 16.0129 52.7816 16.9687 52.7816 18.1075V27.1675H48.938V18.1075C48.938 16.5213 48.7651 15.4536 48.4194 14.9045C48.094 14.3554 47.5042 14.0809 46.6501 14.0809C45.918 14.0809 45.2774 14.4673 44.7283 15.2401C44.1792 16.0129 43.9046 16.9687 43.9046 18.1075V27.1675H40V11.3049Z" fill="#ffffff" stroke-width="3" paint-order="stroke"/><path d="M27.3847 25.9178C28.8081 23.5868 30.5287 21.3029 30.9562 18.5589C31.9911 11.9172 26.9381 5.71447 19.956 5.30338C17.4904 5.15838 13.6449 5.12507 11.1992 5.30299C10.0552 5.38607 8.94122 5.89121 8.16887 6.70868C7.71694 7.18718 5.28183 11.1346 5.20651 11.6441C5.02777 12.8495 5.83228 13.8426 7.09035 13.9645C9.18143 14.1667 11.8763 13.9253 14.0309 13.9264C15.8964 13.9272 17.9989 13.8097 19.8339 13.9253C25.9341 14.3093 29.7128 20.5446 27.3249 25.9319L27.3847 25.9178Z" stroke-width="4.96"/><path d="M14.0302 13.9258L10.6029 19.6599C9.96327 20.8096 10.6737 22.3059 12.0613 22.4638C14.1002 22.6962 17.0133 22.4493 19.1606 22.4689C21.213 22.4877 23.197 22.146 24.8203 23.6246C26.1443 24.8308 26.5555 26.7091 25.9192 28.3472L27.3849 25.9175C29.7728 20.5302 25.9338 14.3083 19.8336 13.9246C17.9986 13.809 15.8961 13.927 14.0306 13.9258H14.0302Z" stroke-width="4.96"/><path d="M19.1603 22.469L15.6471 28.3947C15.2098 29.3278 15.7183 30.5509 16.7183 30.9134C17.4381 31.174 21.8747 31.1148 22.7354 30.9463C24.1038 30.6786 25.4299 29.6056 25.9188 28.3477C26.5548 26.7096 26.1436 24.8313 24.82 23.6251C23.1967 22.1461 21.1733 22.5542 19.1209 22.5354L19.1603 22.469Z" stroke-width="4.96"/></g><path d="M146.965 19.2363C146.965 17.5281 146.64 16.2469 145.989 15.3927C145.358 14.5386 144.464 14.1115 143.304 14.1115C142.227 14.1115 141.352 14.5589 140.681 15.4537C140.03 16.3282 139.705 17.5382 139.705 19.0838V19.3889C139.705 20.9751 140.03 22.2055 140.681 23.08C141.352 23.9341 142.227 24.3612 143.304 24.3612C144.382 24.3612 145.257 23.924 145.928 23.0495C146.619 22.1547 146.965 20.8836 146.965 19.2363ZM150.778 19.2363C150.778 21.8598 150.188 23.8934 149.009 25.3373C147.85 26.7609 146.324 27.4727 144.433 27.4727C142.481 27.4727 140.925 26.7304 139.766 25.2458H139.705V33.8787H135.739V11.305H139.461L139.522 13.5319H139.583C140.803 11.844 142.42 11 144.433 11C146.406 11 147.951 11.7016 149.07 13.1048C150.209 14.5081 150.778 16.5519 150.778 19.2363Z" fill="#26282A"/><path d="M126.399 11C128.819 11 130.558 11.4779 131.615 12.4337C132.673 13.3692 133.202 14.8945 133.202 17.0095V22.8969C133.202 24.3409 133.354 25.7644 133.659 27.1676H129.907C129.785 26.4965 129.694 25.7136 129.633 24.8188H129.572C129.002 25.6526 128.229 26.3033 127.253 26.7711C126.297 27.2388 125.25 27.4727 124.111 27.4727C122.627 27.4727 121.437 27.066 120.542 26.2525C119.668 25.4187 119.23 24.2697 119.23 22.8054C119.23 21.0361 119.973 19.6227 121.457 18.5652C122.962 17.4874 125.118 16.9485 127.924 16.9485H129.236V16.857C129.236 15.7791 129.023 15.0267 128.596 14.5996C128.168 14.1725 127.406 13.959 126.308 13.959C124.315 13.959 122.433 14.4166 120.664 15.3317L120.085 12.3727C122.017 11.4576 124.121 11 126.399 11ZM122.952 22.5004C122.952 23.1512 123.145 23.6596 123.532 24.0256C123.918 24.3917 124.447 24.5747 125.118 24.5747C126.277 24.5747 127.253 24.1985 128.046 23.446C128.84 22.6936 129.236 21.7479 129.236 20.6091V19.5719H127.924C126.318 19.5719 125.087 19.8464 124.233 20.3955C123.379 20.9243 122.952 21.6259 122.952 22.5004Z" fill="#26282A"/><path d="M96.1152 11.305H99.7758L99.8673 13.4404H99.9284C101.108 11.8135 102.46 11 103.986 11C104.982 11 105.806 11.2034 106.456 11.6101C107.107 12.0168 107.666 12.6778 108.134 13.5929H108.195C109.517 11.8643 111.073 11 112.862 11C114.571 11 115.811 11.4779 116.584 12.4337C117.377 13.3692 117.774 14.9555 117.774 17.1925V27.1676H113.93V18.1077C113.93 16.5214 113.757 15.4537 113.412 14.9046C113.086 14.3555 112.496 14.081 111.642 14.081C110.91 14.081 110.27 14.4674 109.72 15.2402C109.171 16.013 108.897 16.9688 108.897 18.1077V27.1676H105.053V18.1077C105.053 16.5214 104.88 15.4537 104.535 14.9046C104.209 14.3555 103.619 14.081 102.765 14.081C102.033 14.081 101.393 14.4674 100.844 15.2402C100.294 16.013 100.02 16.9688 100.02 18.1077V27.1676H96.1152V11.305Z" fill="#26282A"/><path d="M90.8503 19.2363C90.8503 17.5281 90.525 16.2469 89.8742 15.3927C89.2438 14.5386 88.3489 14.1115 87.1898 14.1115C86.1119 14.1115 85.2374 14.5589 84.5663 15.4537C83.9155 16.3282 83.5902 17.5382 83.5902 19.0838V19.3889C83.5902 20.9751 83.9155 22.2055 84.5663 23.08C85.2374 23.9341 86.1119 24.3612 87.1898 24.3612C88.2676 24.3612 89.1421 23.924 89.8132 23.0495C90.5046 22.1547 90.8503 20.8836 90.8503 19.2363ZM94.6635 19.2363C94.6635 21.8598 94.0737 23.8934 92.8942 25.3373C91.735 26.7609 90.2097 27.4727 88.3184 27.4727C86.3661 27.4727 84.8104 26.7304 83.6512 25.2458H83.5902V33.8787H79.6245V11.305H83.3461L83.4071 13.5319H83.4681C84.6883 11.844 86.3051 11 88.3184 11C90.2911 11 91.8367 11.7016 92.9552 13.1048C94.094 14.5081 94.6635 16.5519 94.6635 19.2363Z" fill="#26282A"/><path d="M70.2844 11C72.7045 11 74.4432 11.4779 75.5008 12.4337C76.5583 13.3692 77.087 14.8945 77.087 17.0095V22.8969C77.087 24.3409 77.2395 25.7644 77.5446 27.1676H73.7925C73.6705 26.4965 73.5789 25.7136 73.5179 24.8188H73.4569C72.8875 25.6526 72.1147 26.3033 71.1385 26.7711C70.1827 27.2388 69.1354 27.4727 67.9965 27.4727C66.5119 27.4727 65.3223 27.066 64.4274 26.2525C63.553 25.4187 63.1157 24.2697 63.1157 22.8054C63.1157 21.0361 63.858 19.6227 65.3426 18.5652C66.8475 17.4874 69.0032 16.9485 71.8096 16.9485H73.1214V16.857C73.1214 15.7791 72.9078 15.0267 72.4808 14.5996C72.0537 14.1725 71.2911 13.959 70.1929 13.959C68.1999 13.959 66.3187 14.4166 64.5495 15.3317L63.9699 12.3727C65.9018 11.4576 68.0067 11 70.2844 11ZM66.8373 22.5004C66.8373 23.1512 67.0305 23.6596 67.4169 24.0256C67.8033 24.3917 68.3321 24.5747 69.0032 24.5747C70.1624 24.5747 71.1385 24.1985 71.9317 23.446C72.7248 22.6936 73.1214 21.7479 73.1214 20.6091V19.5719H71.8096C70.203 19.5719 68.9727 19.8464 68.1185 20.3955C67.2644 20.9243 66.8373 21.6259 66.8373 22.5004Z" fill="#26282A"/><path d="M40 11.3049H43.6606L43.7521 13.4403H43.8131C44.9927 11.8133 46.345 10.9999 47.8703 10.9999C48.8668 10.9999 49.6904 11.2032 50.3412 11.61C50.992 12.0167 51.5512 12.6777 52.019 13.5928H52.08C53.4019 11.8642 54.9576 10.9999 56.7472 10.9999C58.4555 10.9999 59.6961 11.4778 60.4689 12.4336C61.262 13.3691 61.6586 14.9554 61.6586 17.1924V27.1675H57.8149V18.1075C57.8149 16.5213 57.6421 15.4536 57.2963 14.9045C56.9709 14.3554 56.3812 14.0809 55.527 14.0809C54.7949 14.0809 54.1543 14.4673 53.6052 15.2401C53.0561 16.0129 52.7816 16.9687 52.7816 18.1075V27.1675H48.938V18.1075C48.938 16.5213 48.7651 15.4536 48.4194 14.9045C48.094 14.3554 47.5042 14.0809 46.6501 14.0809C45.918 14.0809 45.2774 14.4673 44.7283 15.2401C44.1792 16.0129 43.9046 16.9687 43.9046 18.1075V27.1675H40V11.3049Z" fill="#26282A"/><path d="M27.3847 25.9178C28.8081 23.5868 30.5287 21.3029 30.9562 18.5589C31.9911 11.9172 26.9381 5.71447 19.956 5.30338C17.4904 5.15838 13.6449 5.12507 11.1992 5.30299C10.0552 5.38607 8.94122 5.89121 8.16887 6.70868C7.71694 7.18718 5.28183 11.1346 5.20651 11.6441C5.02777 12.8495 5.83228 13.8426 7.09035 13.9645C9.18143 14.1667 11.8763 13.9253 14.0309 13.9264C15.8964 13.9272 17.9989 13.8097 19.8339 13.9253C25.9341 14.3093 29.7128 20.5446 27.3249 25.9319L27.3847 25.9178Z" stroke="#3A3838" stroke-width="1.95943" stroke-miterlimit="10"/><path d="M14.0302 13.9258L10.6029 19.6599C9.96327 20.8096 10.6737 22.3059 12.0613 22.4638C14.1002 22.6962 17.0133 22.4493 19.1606 22.4689C21.213 22.4877 23.197 22.146 24.8203 23.6246C26.1443 24.8308 26.5555 26.7091 25.9192 28.3472L27.3849 25.9175C29.7728 20.5302 25.9338 14.3083 19.8336 13.9246C17.9986 13.809 15.8961 13.927 14.0306 13.9258H14.0302Z" stroke="#3A3838" stroke-width="1.95943" stroke-miterlimit="10"/><path d="M19.1603 22.469L15.6471 28.3947C15.2098 29.3278 15.7183 30.5509 16.7183 30.9134C17.4381 31.174 21.8747 31.1148 22.7354 30.9463C24.1038 30.6786 25.4299 29.6056 25.9188 28.3477C26.5548 26.7096 26.1436 24.8313 24.82 23.6251C23.1967 22.1461 21.1733 22.5542 19.1209 22.5354L19.1603 22.469Z" stroke="#3A3838" stroke-width="1.95943" stroke-miterlimit="10"/></svg>';
 var DEFAULT_HREF = "https://mapmap.ai";
@@ -132,6 +582,172 @@ async function navDesignFromThemeUrl(url, fetchImpl) {
   return navDesignFromTheme(theme);
 }
 
+// src/poi-design.ts
+var POI_CATEGORY_COLORS = [
+  ["food_drink", "#e8734a"],
+  ["shopping", "#4a90d9"],
+  ["transport", "#3a86ff"],
+  ["lodging", "#9b6dd6"],
+  ["health", "#e05c6c"],
+  ["culture_leisure", "#3aa675"],
+  ["education", "#d9a13a"],
+  ["services", "#7a8699"]
+];
+var POI_CATEGORY_IDS = POI_CATEGORY_COLORS.map(([id]) => id);
+var POI_CLASS_CATEGORIES = {
+  food_drink: [
+    "restaurant",
+    "fast_food",
+    "cafe",
+    "bar",
+    "pub",
+    "biergarten",
+    "food_court",
+    "alcohol_shop"
+  ],
+  shopping: [
+    "shop",
+    "grocery",
+    "supermarket",
+    "clothing_store",
+    "mall",
+    "department_store",
+    "convenience",
+    "bakery",
+    "marketplace"
+  ],
+  transport: [
+    "railway",
+    "railway_station",
+    "subway",
+    "bus",
+    "bus_station",
+    "ferry_terminal",
+    "aerodrome",
+    "airport",
+    "airfield"
+  ],
+  lodging: [
+    "lodging",
+    "hotel",
+    "motel",
+    "hostel",
+    "guest_house",
+    "camp_site",
+    "caravan_site",
+    "alpine_hut"
+  ],
+  health: ["hospital", "pharmacy", "doctors", "dentist", "veterinary", "clinic"],
+  culture_leisure: [
+    "museum",
+    "theatre",
+    "cinema",
+    "attraction",
+    "park",
+    "stadium",
+    "art_gallery",
+    "zoo",
+    "swimming_pool",
+    "golf",
+    "playground",
+    "cemetery",
+    "garden",
+    "picnic_site",
+    "viewpoint"
+  ],
+  education: ["school", "college", "university", "library", "kindergarten"],
+  services: [
+    "bank",
+    "post",
+    "police",
+    "town_hall",
+    "place_of_worship",
+    "courthouse",
+    "embassy",
+    "fire_station",
+    "community_centre",
+    "toilet",
+    "telephone",
+    "atm"
+  ]
+};
+function builtInPoiColor(categoryId) {
+  return POI_CATEGORY_COLORS.find(([id]) => id === categoryId)?.[1];
+}
+function defaultPoiDesign() {
+  return { version: 1, categories: {} };
+}
+function poiDesignIsDefault(design) {
+  return Object.keys(design.categories).length === 0;
+}
+function isRecord2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function colour(v) {
+  if (typeof v !== "string") return void 0;
+  const t = v.trim();
+  if (t.startsWith("#")) {
+    const hex = t.slice(1);
+    return [3, 4, 6, 8].includes(hex.length) && /^[0-9a-fA-F]+$/.test(hex) ? t : void 0;
+  }
+  for (const prefix of ["rgb(", "rgba(", "hsl(", "hsla("]) {
+    if (t.startsWith(prefix) && t.endsWith(")")) return t;
+  }
+  return void 0;
+}
+function parsePoiDesign(value) {
+  const design = defaultPoiDesign();
+  if (!isRecord2(value) || !isRecord2(value.categories)) return design;
+  for (const id of POI_CATEGORY_IDS) {
+    const raw = value.categories[id];
+    if (!isRecord2(raw)) continue;
+    const category = {};
+    const color = colour(raw.color);
+    const textColor = colour(raw.textColor);
+    if (color !== void 0) category.color = color;
+    if (textColor !== void 0) category.textColor = textColor;
+    if (Object.keys(category).length > 0) design.categories[id] = category;
+  }
+  return design;
+}
+function poiDesignFromTheme(theme) {
+  const extra = theme?.extra;
+  if (typeof extra !== "object" || extra === null || !("poi" in extra)) {
+    return void 0;
+  }
+  return parsePoiDesign(extra.poi);
+}
+async function poiDesignFromThemeUrl(url, fetchImpl) {
+  const doFetch = fetchImpl ?? ((input) => globalThis.fetch(input));
+  const response = await doFetch(url);
+  if (!response.ok) {
+    throw new Error(`fetching theme ${url}: HTTP ${response.status}`);
+  }
+  const theme = await response.json();
+  return poiDesignFromTheme(theme);
+}
+function poiTextColorExpression(design, fallback) {
+  if (!POI_CATEGORY_IDS.some((id) => design.categories[id]?.textColor)) return fallback;
+  const arms = POI_CATEGORY_IDS.filter((id) => id !== "services").flatMap((id) => [
+    POI_CLASS_CATEGORIES[id],
+    design.categories[id]?.textColor ?? fallback
+  ]);
+  return [
+    "match",
+    ["get", "class"],
+    ...arms,
+    design.categories.services?.textColor ?? fallback
+  ];
+}
+function applyPoiDesign(map, design, fallbackTextColor = "#6b6b6b") {
+  const value = poiTextColorExpression(design, fallbackTextColor);
+  for (const layer of map.getStyle()?.layers ?? []) {
+    if (layer.id === "poi-labels" || layer.id.startsWith("poi-labels@")) {
+      map.setPaintProperty(layer.id, "text-color", value);
+    }
+  }
+}
+
 // src/style.ts
 var OSM_ATTRIBUTION = "\xA9 OpenStreetMap contributors";
 var OPENMAPTILES_ATTRIBUTION = "\xA9 OpenMapTiles";
@@ -175,6 +791,46 @@ var PALETTE_SLOTS = [
   ["textSecondary", "#6b6b6b", "#9aa3ad"],
   ["textHalo", "#ffffff", "#12161c"]
 ];
+var FLOW_PARAM_KEYS = ["color", "width", "speed"];
+function validateEffects(effects) {
+  const route = effects.route ?? "none";
+  if (route !== "flow" && route !== "none") {
+    throw new Error(
+      `invalid effects block: unknown route effect ${JSON.stringify(route)}; accepted: "flow", "none"`
+    );
+  }
+  if (!effects.params) return;
+  if (route === "none") {
+    throw new Error(
+      'invalid effects block: "params" requires "route" to name an effect (e.g. "flow")'
+    );
+  }
+  for (const [key, value] of Object.entries(effects.params)) {
+    if (key === "color") {
+      if (typeof value !== "string" || !isCssColour(value)) {
+        throw new Error(
+          `invalid effects block: params.color has invalid colour ${JSON.stringify(value)}; use #rgb/#rrggbb/#rrggbbaa or rgb()/rgba()/hsl()/hsla()`
+        );
+      }
+    } else if (key === "width") {
+      if (typeof value !== "number" || value < 0.5 || value > 40) {
+        throw new Error(
+          `invalid effects block: params.width must be a number between 0.5 and 40 (pixels), got ${JSON.stringify(value)}`
+        );
+      }
+    } else if (key === "speed") {
+      if (typeof value !== "number" || value < 0 || value > 10) {
+        throw new Error(
+          `invalid effects block: params.speed must be a number between 0 and 10 (cycles per second), got ${JSON.stringify(value)}`
+        );
+      }
+    } else {
+      throw new Error(
+        `invalid effects block: unknown params key ${JSON.stringify(key)}; accepted keys: ${FLOW_PARAM_KEYS.join(", ")}`
+      );
+    }
+  }
+}
 function toPmtilesUrl(url) {
   return url.startsWith("pmtiles://") ? url : `pmtiles://${url}`;
 }
@@ -212,18 +868,18 @@ function resolvePalette(theme) {
   }
   return palette;
 }
-function fill(id, sourceLayer, colour, opacity, minzoom) {
+function fill(id, sourceLayer, colour2, opacity, minzoom) {
   const layer = {
     id,
     type: "fill",
     source: "territory",
     "source-layer": sourceLayer,
-    paint: { "fill-color": colour, "fill-opacity": opacity }
+    paint: { "fill-color": colour2, "fill-opacity": opacity }
   };
   if (minzoom !== void 0) layer["minzoom"] = minzoom;
   return layer;
 }
-function symbol(id, sourceLayer, textField, font, textSize, colour, halo, minzoom, extraLayout) {
+function symbol(id, sourceLayer, textField, font, textSize, colour2, halo, minzoom, extraLayout) {
   const layout = {
     "text-field": textField,
     "text-font": font,
@@ -237,7 +893,7 @@ function symbol(id, sourceLayer, textField, font, textSize, colour, halo, minzoo
     "source-layer": sourceLayer,
     layout,
     paint: {
-      "text-color": colour,
+      "text-color": colour2,
       "text-halo-color": halo,
       "text-halo-width": 1.2
     }
@@ -295,10 +951,20 @@ var THEME_KEYS = [
   "sprite",
   "extra_layers",
   "extra",
-  "buildings_3d"
+  "buildings_3d",
+  "effects"
 ];
+var EFFECTS_METADATA_KEY = "mapmap:effects";
+function effectsFromStyleMetadata(metadata) {
+  if (typeof metadata !== "object" || metadata === null) return void 0;
+  const block = metadata[EFFECTS_METADATA_KEY];
+  if (typeof block !== "object" || block === null) return void 0;
+  const { route, params } = block;
+  if (route !== "flow") return void 0;
+  return typeof params === "object" && params !== null ? { route, params } : { route };
+}
 var BUILDINGS_3D_MINZOOM = 15;
-function buildings3dLayer(colour) {
+function buildings3dLayer(colour2) {
   return {
     id: "building-3d",
     type: "fill-extrusion",
@@ -306,7 +972,7 @@ function buildings3dLayer(colour) {
     "source-layer": "building",
     minzoom: BUILDINGS_3D_MINZOOM,
     paint: {
-      "fill-extrusion-color": colour,
+      "fill-extrusion-color": colour2,
       "fill-extrusion-height": [
         "interpolate",
         ["linear"],
@@ -330,6 +996,11 @@ function buildings3dLayer(colour) {
     }
   };
 }
+function nameFieldFor(labelLanguage) {
+  if (labelLanguage === "local") return ["get", "name"];
+  if (labelLanguage) return ["coalesce", ["get", `name:${labelLanguage}`], ["get", "name"]];
+  return ["coalesce", ["get", "name:en"], ["get", "name"]];
+}
 function buildStyle(options = {}) {
   const input = options.theme ?? "light";
   if (typeof input === "object") {
@@ -345,7 +1016,7 @@ function buildStyle(options = {}) {
   const palette = resolvePalette(theme);
   const p = (slot) => palette[slot];
   const font = [theme.fonts?.regular ?? "Noto Sans Regular"];
-  const nameField = ["coalesce", ["get", "name:en"], ["get", "name"]];
+  const nameField = nameFieldFor(options.labelLanguage);
   const tilesUrl = toPmtilesUrl(
     options.territoryTilesUrl ?? DEFAULT_TERRITORY_TILES_URL
   );
@@ -536,15 +1207,40 @@ function buildStyle(options = {}) {
       p("textHalo"),
       10
     ),
-    symbol(
-      "place-labels",
-      "place",
-      nameField,
-      font,
-      ["interpolate", ["linear"], ["zoom"], 4, 11, 12, 16],
-      p("textPrimary"),
-      p("textHalo")
-    )
+    // Label hierarchy: settlements and regions wait until z4 so world
+    // zooms aren't a flat democracy of states, cities and villages;
+    // continent labels are dropped entirely as clutter.
+    {
+      ...symbol(
+        "place-labels",
+        "place",
+        nameField,
+        font,
+        ["interpolate", ["linear"], ["zoom"], 4, 10.5, 12, 16],
+        p("textPrimary"),
+        p("textHalo"),
+        4
+      ),
+      filter: ["match", ["get", "class"], ["country", "continent"], false, true]
+    },
+    // Countries: the most prominent text on the map at world zooms —
+    // larger, letter-spaced, visible from z1, ceding to the regional
+    // hierarchy from z10. Drawn last = wins label collisions.
+    {
+      ...symbol(
+        "country-labels",
+        "place",
+        nameField,
+        font,
+        ["interpolate", ["linear"], ["zoom"], 1, 11, 3, 13.5, 6, 18],
+        p("textPrimary"),
+        p("textHalo"),
+        1,
+        { "text-letter-spacing": 0.08, "text-max-width": 7 }
+      ),
+      filter: ["==", ["get", "class"], "country"],
+      maxzoom: 10
+    }
   );
   const seenIds = /* @__PURE__ */ new Set();
   for (const layer of layers) {
@@ -580,6 +1276,14 @@ function buildStyle(options = {}) {
     layers
   };
   if (theme.sprite !== void 0) style["sprite"] = theme.sprite;
+  if (theme.effects) {
+    validateEffects(theme.effects);
+    if ((theme.effects.route ?? "none") !== "none") {
+      const block = { route: theme.effects.route };
+      if (theme.effects.params) block["params"] = theme.effects.params;
+      style["metadata"] = { [EFFECTS_METADATA_KEY]: block };
+    }
+  }
   return style;
 }
 
@@ -594,12 +1298,37 @@ function registerPmtilesProtocol(gl = maplibregl) {
 var DEFAULT_BASE_URL = "https://api.mapmap.ai";
 var DEFAULT_CENTER = [-1.5, 52.6];
 var DEFAULT_ZOOM = 5;
+var DEFAULT_EFFECT_LAYER_ID = "mapmap-route-effect";
+function flowOptionsFromParams(params) {
+  const options = {};
+  if (typeof params["color"] === "string") options.color = params["color"];
+  if (typeof params["width"] === "number") options.width = params["width"];
+  if (typeof params["speed"] === "number") options.speed = params["speed"];
+  return options;
+}
 var MapMapMap = class {
   constructor(options) {
+    // Route-effect state (see setRouteEffect / effects.ts). `explicit`
+    // records an app-level decision, which always wins over a style's
+    // metadata auto-enable.
+    this.effectName = null;
+    this.effectOptions = {};
+    this.effectExplicit = false;
+    this.handleStyleLoadForEffects = () => {
+      if (!this.effectExplicit) {
+        const block = effectsFromStyleMetadata(this.styleMetadata());
+        this.effectName = block?.route ?? null;
+        this.effectOptions = block?.params ? flowOptionsFromParams(block.params) : {};
+      }
+      this.effectLayer = void 0;
+      queueMicrotask(() => this.applyRouteEffect());
+    };
     registerPmtilesProtocol();
     this.apiKey = options.apiKey;
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-    this.navDesign = navDesignFromTheme(themeOf(options.style));
+    const theme = themeOf(options.style);
+    this.navDesign = navDesignFromTheme(theme);
+    this.poiDesign = poiDesignFromTheme(theme);
     const style = resolveStyle(options.style, options.territoryTilesUrl);
     this.map = new maplibregl.Map({
       container: options.container,
@@ -616,6 +1345,102 @@ var MapMapMap = class {
         logoOptions.position ?? "bottom-right"
       );
     }
+    this.map.on("style.load", this.handleStyleLoadForEffects);
+    runMapDiagnostics({
+      container: options.container,
+      map: this.map,
+      maplibre: maplibregl,
+      apiKey: this.apiKey
+    });
+  }
+  /** The current style's `metadata`, if it can be read yet. */
+  styleMetadata() {
+    try {
+      return this.map.getStyle?.()?.metadata;
+    } catch {
+      return void 0;
+    }
+  }
+  /**
+   * Set (or clear) the visual effect on the active route line - the
+   * effects-engine entry point (see `effects.ts`). The first effect is
+   * `"flow"`: an animated energy ribbon flowing along the route, drawn in
+   * a MapLibre custom layer with first-party GLSL.
+   *
+   * ```ts
+   * const route = await routes.route(from, to);
+   * map.setRouteEffect("flow");                       // uses the drawn route
+   * map.setRouteEffect("flow", { color: "#ff7a1f" }); // options
+   * map.setRouteEffect(null);                          // back to the plain line
+   * ```
+   *
+   * Geometry: pass `{ geometry }` explicitly, or omit it and the effect
+   * attaches to whatever route a `RouteLayer` on this map draws (current
+   * and future - RouteLayer reports every drawn line via
+   * {@link setRouteEffectGeometry}).
+   *
+   * Styles whose theme carried an `effects` block auto-enable their effect
+   * from the compiled style's metadata; calling this method (with any
+   * value, including `null`) overrides the style's wish for the lifetime
+   * of this map.
+   *
+   * Accessibility/resilience (see effects.ts): honours
+   * `prefers-reduced-motion` (static gradient, no animation) and falls
+   * back to the plain route line with a single console warning if WebGL
+   * setup fails.
+   */
+  setRouteEffect(effect, options = {}) {
+    this.effectExplicit = true;
+    const { geometry, ...flowOptions } = options;
+    this.effectName = effect;
+    this.effectOptions = flowOptions;
+    if (geometry) this.effectGeometry = geometry;
+    this.removeEffectLayer();
+    this.applyRouteEffect();
+  }
+  /**
+   * Attach the active route effect to a route line (or detach it with
+   * `null`). `RouteLayer` calls this on every `draw()`/`clear()`, so apps
+   * normally never do - pass `geometry` to {@link setRouteEffect} for
+   * routes drawn outside a RouteLayer.
+   */
+  setRouteEffectGeometry(geometry) {
+    this.effectGeometry = geometry ?? void 0;
+    if (geometry && this.effectLayer && this.map.getLayer(this.effectLayerId())) {
+      this.effectLayer.setGeometry(geometry);
+      return;
+    }
+    this.applyRouteEffect();
+  }
+  effectLayerId() {
+    return this.effectOptions.id ?? DEFAULT_EFFECT_LAYER_ID;
+  }
+  removeEffectLayer() {
+    const id = this.effectLayerId();
+    if (this.map.getLayer(id)) this.map.removeLayer(id);
+    this.effectLayer = void 0;
+  }
+  /** Reconcile the effect state with the map: install, update or remove. */
+  applyRouteEffect() {
+    const id = this.effectLayerId();
+    if (this.effectName === null || this.effectGeometry === void 0) {
+      this.removeEffectLayer();
+      return;
+    }
+    if (!this.map.isStyleLoaded()) {
+      this.map.once("load", () => this.applyRouteEffect());
+      return;
+    }
+    if (this.effectLayer && this.map.getLayer(id)) {
+      this.effectLayer.setGeometry(this.effectGeometry);
+      return;
+    }
+    if (this.map.getLayer(id)) this.map.removeLayer(id);
+    this.effectLayer = createRouteEffect(this.effectName, this.effectGeometry, {
+      ...this.effectOptions,
+      id
+    });
+    this.map.addLayer(this.effectLayer);
   }
   /**
    * Toggle 3D building extrusions at runtime — the live equivalent of
@@ -644,9 +1469,9 @@ var MapMapMap = class {
     }
     const minzoom = building.minzoom ?? 13;
     if (enabled) {
-      const colour = this.map.getPaintProperty("building", "fill-color") ?? "#e2ddd4";
+      const colour2 = this.map.getPaintProperty("building", "fill-color") ?? "#e2ddd4";
       this.map.addLayer(
-        buildings3dLayer(colour),
+        buildings3dLayer(colour2),
         buildings3dBeforeId(this.map)
       );
       this.map.setLayerZoomRange("building", minzoom, BUILDINGS_3D_MINZOOM);
@@ -702,39 +1527,6 @@ function resolveStyle(style, territoryTilesUrl) {
   return style;
 }
 
-// src/coords.ts
-function toLngLat(point) {
-  if (Array.isArray(point)) {
-    const [lng2, lat2] = point;
-    assertFinite(lng2, lat2);
-    return [lng2, lat2];
-  }
-  const lng = "lng" in point ? point.lng : point.lon;
-  const lat = point.lat;
-  assertFinite(lng, lat);
-  return [lng, lat];
-}
-function formatCoord(point) {
-  const [lng, lat] = toLngLat(point);
-  return `${lng},${lat}`;
-}
-function formatCoords(points) {
-  if (points.length < 2) {
-    throw new Error("at least two coordinates are required for a route");
-  }
-  return points.map(formatCoord).join(";");
-}
-function assertFinite(lng, lat) {
-  if (!Number.isFinite(lng) || !Number.isFinite(lat)) {
-    throw new Error(`invalid coordinate: lng=${lng}, lat=${lat}`);
-  }
-  if (lng < -180 || lng > 180 || lat < -90 || lat > 90) {
-    throw new Error(
-      `coordinate out of range: lng=${lng} (\xB1180), lat=${lat} (\xB190) - check lng/lat order`
-    );
-  }
-}
-
 // src/osrm.ts
 function buildRouteQuery(truck, guidance) {
   const params = new URLSearchParams({
@@ -808,13 +1600,42 @@ function numberOr(value, fallback) {
 // src/route.ts
 var SIGNAL_BLUE = "#3a86ff";
 var CASING_COLOR = "#1f438a";
+var PROGRESS_COLOR = "#b0b0b0";
+function arrowImage() {
+  const size = 24;
+  const data = new Uint8Array(size * size * 4);
+  const head = 13;
+  const put = (x, y, edge) => {
+    const i = (y * size + x) * 4;
+    const v = edge ? 31 : 255;
+    data[i] = v;
+    data[i + 1] = v;
+    data[i + 2] = edge ? 58 : 255;
+    data[i + 3] = 255;
+  };
+  for (let y = 2; y < head; y++) {
+    const half = Math.round((y - 2) / (head - 3) * 9);
+    for (let x = 11 - half; x <= 12 + half; x++) {
+      put(x, y, x === 11 - half || x === 12 + half || y === 2);
+    }
+  }
+  for (let y = head; y < 22; y++) {
+    for (let x = 9; x <= 14; x++) {
+      put(x, y, x === 9 || x === 14 || y === 21);
+    }
+  }
+  return { width: size, height: size, data };
+}
 var RouteLayer = class {
   constructor(map, options = {}) {
+    this.progress = 0;
     this.handleStyleLoad = () => {
       if (this.lastRoute) this.install(this.lastRoute);
+      else this.installManeuver();
     };
     if (map instanceof MapMapMap) {
       this.map = map.map;
+      this.owner = map;
       this.baseUrl = (options.baseUrl ?? map.baseUrl).replace(/\/+$/, "");
       this.apiKey = options.apiKey ?? map.apiKey;
       this.design = options.design ?? map.navDesign?.route;
@@ -831,6 +1652,10 @@ var RouteLayer = class {
     this.sourceId = `${id}-src`;
     this.casingLayerId = `${id}-casing`;
     this.lineLayerId = `${id}-line`;
+    this.maneuverSourceId = `${id}-maneuver-src`;
+    this.maneuverLayerId = `${id}-maneuver`;
+    this.arrowImageId = `${id}-arrow`;
+    this.progressColor = options.progressColor ?? PROGRESS_COLOR;
     this.map.on("style.load", this.handleStyleLoad);
   }
   /**
@@ -878,8 +1703,8 @@ var RouteLayer = class {
    */
   draw(route) {
     this.lastRoute = route;
-    if (!this.map.isStyleLoaded()) return;
-    this.install(route);
+    if (this.map.isStyleLoaded()) this.install(route);
+    this.owner?.setRouteEffectGeometry(route.geometry);
   }
   /** Add-or-update the source and layers for a route on the current style. */
   install(route) {
@@ -892,9 +1717,11 @@ var RouteLayer = class {
     if (existing) {
       existing.setData(data);
     } else {
-      this.map.addSource(this.sourceId, { type: "geojson", data });
+      this.map.addSource(this.sourceId, { type: "geojson", data, lineMetrics: true });
     }
     if (this.map.getLayer(this.casingLayerId) && this.map.getLayer(this.lineLayerId)) {
+      this.applyProgress();
+      this.installManeuver();
       return;
     }
     const casing = {
@@ -927,14 +1754,86 @@ var RouteLayer = class {
     };
     if (!this.map.getLayer(this.casingLayerId)) this.map.addLayer(casing);
     if (!this.map.getLayer(this.lineLayerId)) this.map.addLayer(line);
+    this.applyProgress();
+    this.installManeuver();
+  }
+  /**
+   * Sets how much of the route has been travelled, as a fraction in `[0, 1]`
+   * of the line's length. The travelled part dims to `progressColor` (the
+   * "vanishing route line"); `0` restores the untinted line. The value is
+   * remembered across {@link draw} calls and style swaps. Pair with the
+   * guidance module's distance-remaining to derive the fraction.
+   */
+  setProgress(fraction) {
+    this.progress = Math.min(1, Math.max(0, fraction));
+    if (this.map.getLayer(this.lineLayerId)) this.applyProgress();
+  }
+  /** Applies the current progress fraction to the line layer's gradient. */
+  applyProgress() {
+    const routeColor = this.design?.color ?? SIGNAL_BLUE;
+    const gradient = this.progress > 0 ? ["step", ["line-progress"], this.progressColor, this.progress, routeColor] : void 0;
+    this.map.setPaintProperty(this.lineLayerId, "line-gradient", gradient);
+  }
+  /**
+   * Shows (or moves) the upcoming-manoeuvre arrow: a small map-aligned
+   * arrow at `lngLat` rotated to `bearingDeg` (clockwise from north).
+   * Survives style swaps until {@link clearManeuver}.
+   */
+  setManeuver(lngLat, bearingDeg) {
+    this.maneuver = { lngLat, bearingDeg };
+    if (this.map.isStyleLoaded()) this.installManeuver();
+  }
+  /** Hides the manoeuvre arrow. */
+  clearManeuver() {
+    this.maneuver = void 0;
+    if (this.map.getLayer(this.maneuverLayerId)) this.map.removeLayer(this.maneuverLayerId);
+    if (this.map.getSource(this.maneuverSourceId)) this.map.removeSource(this.maneuverSourceId);
+  }
+  /** Add-or-update the manoeuvre arrow source/layer for the current style. */
+  installManeuver() {
+    if (!this.maneuver) return;
+    const data = {
+      type: "Feature",
+      properties: { bearing: this.maneuver.bearingDeg },
+      geometry: { type: "Point", coordinates: this.maneuver.lngLat }
+    };
+    const source = this.map.getSource(this.maneuverSourceId);
+    if (source) {
+      source.setData(data);
+    } else {
+      this.map.addSource(this.maneuverSourceId, { type: "geojson", data });
+    }
+    if (!this.map.hasImage(this.arrowImageId)) {
+      this.map.addImage(this.arrowImageId, arrowImage());
+    }
+    if (!this.map.getLayer(this.maneuverLayerId)) {
+      this.map.addLayer({
+        id: this.maneuverLayerId,
+        type: "symbol",
+        source: this.maneuverSourceId,
+        layout: {
+          "icon-image": this.arrowImageId,
+          "icon-rotate": ["get", "bearing"],
+          "icon-rotation-alignment": "map",
+          "icon-allow-overlap": true,
+          "icon-ignore-placement": true,
+          "icon-size": ["interpolate", ["linear"], ["zoom"], 12, 0.7, 18, 1.4]
+        }
+      });
+    } else {
+      this.map.setLayoutProperty(this.maneuverLayerId, "icon-rotate", ["get", "bearing"]);
+    }
   }
   /** Remove the route's layers and source from the map. */
   clear() {
+    this.clearManeuver();
     for (const layerId of [this.lineLayerId, this.casingLayerId]) {
       if (this.map.getLayer(layerId)) this.map.removeLayer(layerId);
     }
     if (this.map.getSource(this.sourceId)) this.map.removeSource(this.sourceId);
     this.lastRoute = void 0;
+    this.owner?.setRouteEffectGeometry(null);
+    this.progress = 0;
   }
   /**
    * Remove the route and detach the layer's `style.load` listener. Call
@@ -960,6 +1859,12 @@ function effectiveImageUrl(design) {
   }
   return url;
 }
+function shortestArcDeg(fromDeg, toDeg) {
+  const raw = ((toDeg - fromDeg) % 360 + 360) % 360;
+  return raw > 180 ? raw - 360 : raw;
+}
+var MAX_TWEEN_MS = 900;
+var MIN_TWEEN_MS = 100;
 var PositionPuck = class {
   /**
    * Creates the puck (not yet on the map - it appears on the first
@@ -967,12 +1872,17 @@ var PositionPuck = class {
    * `navDesign.puck` when given a `MapMapMap` whose theme carried an
    * `extra.nav` block, then to the built-in blue puck.
    */
-  constructor(map, design) {
+  constructor(map, design, options) {
     this.added = false;
     this.map = map instanceof MapMapMap ? map.map : map;
     this.design = design ?? (map instanceof MapMapMap ? map.navDesign?.puck : void 0) ?? defaultNavDesign().puck;
     this.element = createPuckElement();
     stylePuckElement(this.element, this.design);
+    this.interpolate = options?.interpolate ?? true;
+    this.now = options?.now ?? Date.now;
+    const g = globalThis;
+    this.requestFrame = options?.requestFrame ?? (g.requestAnimationFrame ? (cb) => g.requestAnimationFrame(() => cb()) : void 0);
+    this.cancelFrame = options?.cancelFrame ?? (g.cancelAnimationFrame ? (h) => g.cancelAnimationFrame(h) : void 0);
     this.marker = new maplibregl.Marker({
       element: this.element,
       rotationAlignment: "map",
@@ -983,20 +1893,72 @@ var PositionPuck = class {
    * Moves the puck (adding it to the map on the first call). `headingDeg`
    * rotates the whole element - arrow or custom image - clockwise from
    * north; omit it to keep the previous heading.
+   *
+   * With interpolation on (the default) every call after the first glides
+   * from the currently rendered position - a fix arriving mid-tween
+   * retargets smoothly rather than jumping.
    */
   setLocation(location, headingDeg) {
-    this.marker.setLngLat([location.lon, location.lat]);
-    if (headingDeg !== void 0) this.marker.setRotation(headingDeg);
-    if (!this.added) {
+    const first = !this.added;
+    const nowMs = this.now();
+    const interval = this.lastFixAt === void 0 ? MAX_TWEEN_MS : nowMs - this.lastFixAt;
+    this.lastFixAt = nowMs;
+    this.cancelTween();
+    const from = this.rendered;
+    const target = {
+      lat: location.lat,
+      lon: location.lon,
+      heading: headingDeg ?? from?.heading ?? 0
+    };
+    const duration = Math.min(MAX_TWEEN_MS, interval);
+    if (first || !this.interpolate || !this.requestFrame || !from || duration < MIN_TWEEN_MS) {
+      this.render(target);
+    } else {
+      this.tween(from, target, nowMs, duration);
+    }
+    if (first) {
       this.marker.addTo(this.map);
       this.added = true;
     }
   }
-  /** Removes the puck from the map. `setLocation` re-adds it. */
+  /** Removes the puck from the map (cancelling any tween). `setLocation` re-adds it. */
   remove() {
+    this.cancelTween();
     this.marker.remove();
     this.added = false;
   }
+  /** Applies a position/heading to the marker immediately. */
+  render(state) {
+    this.marker.setLngLat([state.lon, state.lat]);
+    this.marker.setRotation(state.heading);
+    this.rendered = state;
+  }
+  /** Runs a linear position lerp + shortest-arc heading tween via rAF. */
+  tween(from, to, startedAt, duration) {
+    const headingDelta = shortestArcDeg(from.heading, to.heading);
+    const step = () => {
+      const t = Math.min(1, (this.now() - startedAt) / duration);
+      this.render({
+        lat: from.lat + (to.lat - from.lat) * t,
+        lon: from.lon + (to.lon - from.lon) * t,
+        heading: from.heading + headingDelta * t
+      });
+      if (t < 1) {
+        this.frameHandle = this.requestFrame(step);
+      } else {
+        this.frameHandle = void 0;
+        this.render(to);
+      }
+    };
+    this.frameHandle = this.requestFrame(step);
+  }
+  /** Cancels an in-flight tween, leaving the marker where it rendered last. */
+  cancelTween() {
+    if (this.frameHandle !== void 0) {
+      this.cancelFrame?.(this.frameHandle);
+      this.frameHandle = void 0;
+    }
+  }
 };
 function createPuckElement() {
   const doc = globalThis.document;
@@ -1045,7 +2007,187 @@ function stylePuckElement(el, puck) {
   dot.style.cssText = `position:absolute;inset:0;border-radius:50%;background:${puck.color};border:2px solid #ffffff;box-shadow:0 1px 6px rgba(0,0,0,0.45)`;
   arrow.style.cssText = puck.headingArrow ? `position:absolute;left:50%;top:${(-s * 0.55).toFixed(1)}px;transform:translateX(-50%);width:0;height:0;border-left:${(s * 0.35).toFixed(1)}px solid transparent;border-right:${(s * 0.35).toFixed(1)}px solid transparent;border-bottom:${(s * 0.6).toFixed(1)}px solid ${puck.color}` : "display:none";
 }
-var EARTH_RADIUS_M = 63710088e-1;
+
+// src/daynight.ts
+var DEG = Math.PI / 180;
+var DAY_MS = 864e5;
+var JULIAN_EPOCH = 24405875e-1;
+var J2000 = 2451545;
+function fromJulian(julian) {
+  return new Date((julian - JULIAN_EPOCH) * DAY_MS);
+}
+function sunTimes(date, lat, lng) {
+  const julianDay = Math.ceil(date.getTime() / DAY_MS + JULIAN_EPOCH - J2000 - 9e-4 + lng / 360);
+  const meanSolarTime = julianDay + 9e-4 - lng / 360;
+  const meanAnomalyDeg = (357.5291 + 0.98560028 * meanSolarTime) % 360;
+  const m = meanAnomalyDeg * DEG;
+  const centreDeg = 1.9148 * Math.sin(m) + 0.02 * Math.sin(2 * m) + 3e-4 * Math.sin(3 * m);
+  const eclipticLngDeg = (meanAnomalyDeg + centreDeg + 180 + 102.9372) % 360;
+  const l = eclipticLngDeg * DEG;
+  const transit = J2000 + meanSolarTime + 53e-4 * Math.sin(m) - 69e-4 * Math.sin(2 * l);
+  const sinDeclination = Math.sin(l) * Math.sin(23.4397 * DEG);
+  const cosDeclination = Math.cos(Math.asin(sinDeclination));
+  const cosHourAngle = (Math.sin(-0.833 * DEG) - Math.sin(lat * DEG) * sinDeclination) / (Math.cos(lat * DEG) * cosDeclination);
+  if (cosHourAngle < -1) return "polarDay";
+  if (cosHourAngle > 1) return "polarNight";
+  const hourAngleDeg = Math.acos(cosHourAngle) / DEG;
+  return {
+    sunrise: fromJulian(transit - hourAngleDeg / 360),
+    sunset: fromJulian(transit + hourAngleDeg / 360)
+  };
+}
+function resolveTheme(date, lat, lng) {
+  const times = sunTimes(date, lat, lng);
+  if (times === "polarDay") return "light";
+  if (times === "polarNight") return "dark";
+  return date >= times.sunrise && date < times.sunset ? "light" : "dark";
+}
+var POLAR_RECHECK_MS = 6 * 36e5;
+var BOUNDARY_MARGIN_MS = 1e3;
+var ThemeScheduler = class {
+  constructor(options) {
+    this.disposed = false;
+    this.lat = options.lat;
+    this.lng = options.lng;
+    this.onLight = options.onLight;
+    this.onDark = options.onDark;
+    this.now = options.now ?? Date.now;
+    this.setTimeoutFn = options.setTimeoutFn ?? ((cb, ms) => setTimeout(cb, ms));
+    this.clearTimeoutFn = options.clearTimeoutFn ?? ((h) => clearTimeout(h));
+    this.evaluate();
+  }
+  /** The theme most recently applied, if any. */
+  get current() {
+    return this.applied;
+  }
+  /** Moves the observer (e.g. a new GPS fix region) and re-evaluates. */
+  setPosition(lat, lng) {
+    this.lat = lat;
+    this.lng = lng;
+    this.evaluate();
+  }
+  /** Stops all future flips. */
+  dispose() {
+    this.disposed = true;
+    if (this.handle !== void 0) this.clearTimeoutFn(this.handle);
+    this.handle = void 0;
+  }
+  /** Applies the theme for now and arms the timer for the next boundary. */
+  evaluate() {
+    if (this.disposed) return;
+    if (this.handle !== void 0) {
+      this.clearTimeoutFn(this.handle);
+      this.handle = void 0;
+    }
+    const nowDate = new Date(this.now());
+    const theme = resolveTheme(nowDate, this.lat, this.lng);
+    if (theme !== this.applied) {
+      this.applied = theme;
+      (theme === "light" ? this.onLight : this.onDark)();
+    }
+    const delay = this.nextBoundaryDelay(nowDate);
+    this.handle = this.setTimeoutFn(() => this.evaluate(), delay);
+  }
+  /** Milliseconds until the next sunrise/sunset (or the polar re-check). */
+  nextBoundaryDelay(nowDate) {
+    const nowMs = nowDate.getTime();
+    for (const dayOffset of [0, 1]) {
+      const times = sunTimes(new Date(nowMs + dayOffset * DAY_MS), this.lat, this.lng);
+      if (times === "polarDay" || times === "polarNight") continue;
+      for (const event of [times.sunrise, times.sunset]) {
+        const delta = event.getTime() - nowMs;
+        if (delta > 0) return delta + BOUNDARY_MARGIN_MS;
+      }
+    }
+    return POLAR_RECHECK_MS;
+  }
+};
+
+// src/language.ts
+var LANGUAGE_TAG = /^[a-z]{2,3}(-[A-Za-z0-9]{2,4})?$/;
+function languageTextField(language) {
+  if (language === null) {
+    return ["coalesce", ["get", "name:en"], ["get", "name"]];
+  }
+  return [
+    "coalesce",
+    ["get", `name:${language}`],
+    ["get", "name:latin"],
+    ["get", "name"]
+  ];
+}
+function isNameTextField(textField) {
+  if (typeof textField === "string") {
+    return /\{name(?::[A-Za-z0-9-]+)?\}/.test(textField);
+  }
+  if (Array.isArray(textField)) {
+    if (textField.length === 2 && textField[0] === "get" && typeof textField[1] === "string") {
+      return textField[1] === "name" || textField[1].startsWith("name:");
+    }
+    return textField.some((part) => isNameTextField(part));
+  }
+  return false;
+}
+function setMapLanguage(map, language) {
+  if (language !== null && !LANGUAGE_TAG.test(language)) {
+    throw new Error(
+      `invalid language tag ${JSON.stringify(language)}; use e.g. "de", "pt-BR", "zh-Hans"`
+    );
+  }
+  const ml = map instanceof MapMapMap ? map.map : map;
+  const layers = ml.getStyle()?.layers ?? [];
+  const changed = [];
+  for (const layer of layers) {
+    if (layer.type !== "symbol") continue;
+    const textField = layer.layout?.["text-field"];
+    if (textField === void 0 || !isNameTextField(textField)) continue;
+    ml.setLayoutProperty(layer.id, "text-field", languageTextField(language));
+    changed.push(layer.id);
+  }
+  return changed;
+}
+
+// src/probe.ts
+function buildProbeUrl(baseUrl) {
+  return `${baseUrl.replace(/\/+$/, "")}/v1/probe`;
+}
+async function uploadProbeBatch(baseUrl, apiKey, body, options = {}) {
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const maxAttempts = options.maxAttempts ?? 4;
+  const backoffMs = options.backoffMs ?? ((attempt) => attempt * 1e3);
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const url = buildProbeUrl(baseUrl);
+  for (let attempt = 1; ; attempt++) {
+    let outcome;
+    try {
+      const response = await doFetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body,
+        signal: options.signal
+      });
+      outcome = classifyStatus(response.status);
+    } catch {
+      outcome = "gaveUp";
+    }
+    if (outcome === "gaveUp" && attempt < maxAttempts) {
+      await sleep(backoffMs(attempt));
+      continue;
+    }
+    return outcome;
+  }
+}
+function classifyStatus(status) {
+  if (status === 202) return "accepted";
+  if (status === 403) return "refused";
+  if (status === 501) return "notEnabled";
+  if (status >= 500 && status <= 599) return "gaveUp";
+  return "rejected";
+}
+var EARTH_RADIUS_M2 = 63710088e-1;
 var CLUSTER_TEXT_FONT = "Noto Sans Regular";
 function placesFromGeoJSON(collection) {
   const places = [];
@@ -1073,7 +2215,7 @@ function haversineDistanceM(a, b) {
   const dLat = rad(b.lat - a.lat);
   const dLon = rad(b.lon - a.lon);
   const h = Math.sin(dLat / 2) ** 2 + Math.cos(rad(a.lat)) * Math.cos(rad(b.lat)) * Math.sin(dLon / 2) ** 2;
-  return 2 * EARTH_RADIUS_M * Math.asin(Math.sqrt(h));
+  return 2 * EARTH_RADIUS_M2 * Math.asin(Math.sqrt(h));
 }
 var PlacesLayer = class {
   constructor(map, options = {}) {
@@ -1134,6 +2276,7 @@ var PlacesLayer = class {
     this.clusterRadius = options.clusterRadius;
     this.clusterMaxZoom = options.clusterMaxZoom;
     this.color = options.color ?? SIGNAL_BLUE;
+    this.clusterColor = options.clusterColor ?? (typeof this.color === "string" ? this.color : SIGNAL_BLUE);
     this.icon = options.icon;
     this.wantFitBounds = options.fitBounds ?? false;
     this.onPlaceClick = options.onPlaceClick;
@@ -1151,9 +2294,12 @@ var PlacesLayer = class {
   }
   /**
    * Replace the layer's places - a `Place[]` or a GeoJSON FeatureCollection
-   * of Points. Updates the existing GeoJSON source in place; safe to call
-   * before the style has loaded (installed on the next `style.load`). With
-   * `fitBounds: true` the first non-empty set also fits the map view.
+   * of Points. Never silently drops an update: once the source exists the
+   * data is applied immediately, even while `isStyleLoaded()` is transiently
+   * `false` mid-render (search-as-you-type just works); calls made before
+   * the source has first been installed are stashed - the latest one wins -
+   * and installed on the next `style.load`. With `fitBounds: true` the
+   * first non-empty set also fits the map view.
    */
   setPlaces(places) {
     this.places = Array.isArray(places) ? places : placesFromGeoJSON(places);
@@ -1174,13 +2320,59 @@ var PlacesLayer = class {
       this.fitted = true;
       this.map.fitBounds(boundsOf(this.places), { padding: 48, maxZoom: 15 });
     }
-    if (!this.map.isStyleLoaded()) return;
-    this.install(this.data);
+    const source = this.map.getSource(this.sourceId);
+    if (source) {
+      source.setData(this.data);
+    } else if (this.map.isStyleLoaded()) {
+      this.install(this.data);
+    }
   }
   /** The layer's current places (normalised to `Place[]`). */
   get current() {
     return this.places;
   }
+  /**
+   * The generated MapLibre source/layer ids - public API for escape-hatch
+   * styling (`map.setPaintProperty`, `queryRenderedFeatures`, …) beyond the
+   * layer's options. Stable for the layer's lifetime, derived from the `id`
+   * option (default `"mapmap-places"`). The cluster ids are only installed
+   * on the map with `cluster: true` (the default), and `points` is a circle
+   * layer by default or a symbol layer once a custom `icon` has loaded.
+   */
+  get ids() {
+    return {
+      source: this.sourceId,
+      points: this.pointsLayerId,
+      clusters: this.clustersLayerId,
+      clusterCounts: this.clusterCountLayerId
+    };
+  }
+  /**
+   * Programmatically select a place by id - list-to-map sync for a store
+   * finder's results list. Opens the layer's configured `popup` at the
+   * place (`popup: false` to skip, no-op without a `popup` option) and
+   * eases the camera to it (`flyTo: false` to skip; `zoom` to also zoom).
+   * Returns the selected place, or `undefined` for an unknown id (in which
+   * case nothing happens). Does NOT invoke `onPlaceClick` - a programmatic
+   * selection is not a user click.
+   */
+  select(id, options = {}) {
+    const place = this.places.find((p) => p.id === id);
+    if (!place) return void 0;
+    if (options.flyTo ?? true) {
+      this.map.easeTo({
+        center: [place.lon, place.lat],
+        ...options.zoom !== void 0 ? { zoom: options.zoom } : {}
+      });
+    }
+    if (options.popup ?? true) this.openPopup(place);
+    return place;
+  }
+  /** Close the popup opened by {@link select} or a place click, if any. */
+  deselect() {
+    this.popup?.remove();
+    this.popup = void 0;
+  }
   /**
    * The nearest `n` places (default `1`) to `origin` by straight-line
    * (haversine) distance, each with `distanceM` attached. Pure and instant -
@@ -1269,7 +2461,7 @@ var PlacesLayer = class {
         source: this.sourceId,
         filter: ["has", "point_count"],
         paint: {
-          "circle-color": this.color,
+          "circle-color": this.clusterColor,
           "circle-opacity": 0.9,
           "circle-radius": ["step", ["get", "point_count"], 16, 25, 20, 100, 26],
           "circle-stroke-color": "#ffffff",
@@ -1507,9 +2699,9 @@ var NavigationCamera = class {
    * {@link resume}.
    */
   follow(fix, courseDeg) {
-    const now = Date.now();
-    const interval = this.lastFixAt === void 0 ? this.easeMs : Math.max(0, now - this.lastFixAt);
-    this.lastFixAt = now;
+    const now2 = Date.now();
+    const interval = this.lastFixAt === void 0 ? this.easeMs : Math.max(0, now2 - this.lastFixAt);
+    this.lastFixAt = now2;
     this.lastFix = fix;
     if (courseDeg !== void 0) this.lastCourse = courseDeg;
     this.puck?.setLocation(fix, courseDeg);
@@ -1609,6 +2801,188 @@ function boundsOf2(coordinates) {
     [maxLng, maxLat]
   ];
 }
+var FLYTHROUGH_EARTH_RADIUS_M = 63710088e-1;
+function flythroughDistanceM(a, b) {
+  const rad = (deg) => deg * Math.PI / 180;
+  const dLat = rad(b[1] - a[1]);
+  const dLon = rad(b[0] - a[0]);
+  const h = Math.sin(dLat / 2) ** 2 + Math.cos(rad(a[1])) * Math.cos(rad(b[1])) * Math.sin(dLon / 2) ** 2;
+  return 2 * FLYTHROUGH_EARTH_RADIUS_M * Math.asin(Math.sqrt(h));
+}
+function bearingBetween(a, b) {
+  const rad = (deg2) => deg2 * Math.PI / 180;
+  const dLon = rad(b[0] - a[0]);
+  const latA = rad(a[1]);
+  const latB = rad(b[1]);
+  const y = Math.sin(dLon) * Math.cos(latB);
+  const x = Math.cos(latA) * Math.sin(latB) - Math.sin(latA) * Math.cos(latB) * Math.cos(dLon);
+  const deg = Math.atan2(y, x) * 180 / Math.PI;
+  return (deg + 360) % 360;
+}
+function shortestArcDelta(from, to) {
+  const delta = ((to - from) % 360 + 540) % 360 - 180;
+  return delta === -180 ? 180 : delta;
+}
+var PoseSampler = class {
+  constructor(coordinates) {
+    const unwrapped = unwrapLngs(coordinates);
+    this.points = unwrapped.filter(
+      (p, i) => i === 0 || p[0] !== unwrapped[i - 1][0] || p[1] !== unwrapped[i - 1][1]
+    );
+    if (this.points.length < 2) {
+      throw new Error(
+        "flythrough needs a route with at least two distinct coordinates"
+      );
+    }
+    this.cumulative = [0];
+    for (let i = 1; i < this.points.length; i++) {
+      this.cumulative.push(
+        this.cumulative[i - 1] + flythroughDistanceM(this.points[i - 1], this.points[i])
+      );
+    }
+    this.totalM = this.cumulative[this.cumulative.length - 1];
+  }
+  /** The interpolated point `distanceM` along the route (clamped). */
+  pointAt(distanceM) {
+    const d = Math.min(this.totalM, Math.max(0, distanceM));
+    let i = 1;
+    while (i < this.cumulative.length - 1 && this.cumulative[i] < d) i++;
+    const before = this.cumulative[i - 1];
+    const span = this.cumulative[i] - before;
+    const f = span > 0 ? (d - before) / span : 0;
+    const a = this.points[i - 1];
+    const b = this.points[i];
+    return [a[0] + (b[0] - a[0]) * f, a[1] + (b[1] - a[1]) * f];
+  }
+  /** The pose at progress `t` (clamped 0-1), chasing `lookAheadM` ahead. */
+  poseAt(t, lookAheadM) {
+    const d = Math.min(1, Math.max(0, t)) * this.totalM;
+    const center = this.pointAt(d);
+    let target = this.pointAt(d + Math.max(1, lookAheadM));
+    if (target[0] === center[0] && target[1] === center[1]) {
+      const last = this.points[this.points.length - 1];
+      const prev = this.points[this.points.length - 2];
+      return { center, bearing: bearingBetween(prev, last) };
+    }
+    return { center, bearing: bearingBetween(center, target) };
+  }
+};
+function flythroughPose(coordinates, t, lookAheadM = 200) {
+  return new PoseSampler(coordinates).poseAt(t, lookAheadM);
+}
+function scheduleFrame(cb) {
+  if (typeof requestAnimationFrame === "function") {
+    const handle2 = requestAnimationFrame(cb);
+    return () => cancelAnimationFrame(handle2);
+  }
+  const handle = setTimeout(() => cb(Date.now()), 16);
+  return () => clearTimeout(handle);
+}
+function flythrough(map, route, options = {}) {
+  const m = map instanceof MapMapMap ? map.map : map;
+  const geometry = "geometry" in route ? route.geometry : route;
+  const sampler = new PoseSampler(geometry.coordinates);
+  const pitch = clamp(options.pitch ?? 60, 0, 85);
+  const zoom = options.zoom ?? 16;
+  const lookAheadM = options.lookAheadM ?? 200;
+  const bearingEase = Math.max(0, options.bearingEase ?? 3);
+  const durationMs = options.speedMps !== void 0 && options.speedMps > 0 ? sampler.totalM / options.speedMps * 1e3 : Math.max(1, options.durationMs ?? 2e4);
+  let t = 0;
+  let rate = 1;
+  let playing = false;
+  let destroyed = false;
+  let bearing;
+  let lastFrameTs;
+  let cancelFrame;
+  const listeners = /* @__PURE__ */ new Set();
+  const applyPose = (dtS) => {
+    const pose = sampler.poseAt(t, lookAheadM);
+    bearing = bearing === void 0 ? pose.bearing : bearing + shortestArcDelta(bearing, pose.bearing) * Math.min(1, bearingEase * dtS);
+    m.jumpTo({ center: pose.center, bearing, pitch, zoom });
+    for (const listener of listeners) listener(t);
+  };
+  const frame = (timestampMs) => {
+    if (!playing || destroyed) return;
+    const dtS = lastFrameTs === void 0 ? 0 : Math.max(0, timestampMs - lastFrameTs) / 1e3;
+    lastFrameTs = timestampMs;
+    t = Math.min(1, t + dtS * 1e3 * rate / durationMs);
+    applyPose(dtS || 1 / 60);
+    if (t >= 1) {
+      playing = false;
+      return;
+    }
+    cancelFrame = scheduleFrame(frame);
+  };
+  const pause = () => {
+    playing = false;
+    cancelFrame?.();
+    cancelFrame = void 0;
+    lastFrameTs = void 0;
+  };
+  return {
+    play() {
+      if (destroyed || playing) return;
+      if (t >= 1) t = 0;
+      playing = true;
+      lastFrameTs = void 0;
+      cancelFrame = scheduleFrame(frame);
+    },
+    pause,
+    stop() {
+      if (destroyed) return;
+      pause();
+      t = 0;
+      bearing = void 0;
+      applyPose(1 / 60);
+    },
+    seek(to) {
+      if (destroyed) return;
+      t = Math.min(1, Math.max(0, to));
+      bearing = void 0;
+      applyPose(1 / 60);
+    },
+    get speed() {
+      return rate;
+    },
+    set speed(value) {
+      if (Number.isFinite(value) && value > 0) rate = value;
+    },
+    get progress() {
+      return t;
+    },
+    get playing() {
+      return playing;
+    },
+    onProgress(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    destroy() {
+      destroyed = true;
+      pause();
+      listeners.clear();
+    }
+  };
+}
+function bindFlythroughToScroll(controller, target = window) {
+  const t = target;
+  const fraction = () => {
+    if (typeof t.scrollTop === "number") {
+      const max2 = (t.scrollHeight ?? 0) - (t.clientHeight ?? 0);
+      return max2 > 0 ? t.scrollTop / max2 : 0;
+    }
+    const doc = t.document?.documentElement;
+    const max = (doc?.scrollHeight ?? 0) - (t.innerHeight ?? 0);
+    return max > 0 ? (t.scrollY ?? 0) / max : 0;
+  };
+  const onScroll = () => {
+    controller.pause();
+    controller.seek(Math.min(1, Math.max(0, fraction())));
+  };
+  t.addEventListener("scroll", onScroll, { passive: true });
+  onScroll();
+  return () => t.removeEventListener("scroll", onScroll);
+}
 function usesGlobe(projection) {
   if (projection === null || projection === void 0) return false;
   if (typeof projection === "string") {
@@ -1621,6 +2995,207 @@ function usesGlobe(projection) {
   return false;
 }
 
+// src/isochrone.ts
+var MODE_TO_COSTING = {
+  walk: "pedestrian",
+  cycle: "bicycle",
+  drive: "auto"
+};
+var IsochroneLayer = class {
+  constructor(map, options = {}) {
+    this.lastMinutes = [];
+    this.lastColor = SIGNAL_BLUE;
+    this.handleStyleLoad = () => {
+      if (this.lastData) this.install(this.lastData);
+    };
+    if (map instanceof MapMapMap) {
+      this.map = map.map;
+      this.baseUrl = (options.baseUrl ?? map.baseUrl).replace(/\/+$/, "");
+      this.apiKey = options.apiKey ?? map.apiKey;
+    } else {
+      this.map = map;
+      if (!options.baseUrl) {
+        throw new Error(
+          "IsochroneLayer needs a baseUrl when given a raw MapLibre map"
+        );
+      }
+      this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+      this.apiKey = options.apiKey;
+    }
+    const id = options.id ?? "mapmap-isochrone";
+    this.sourceId = `${id}-src`;
+    this.fillLayerId = `${id}-fill`;
+    this.lineLayerId = `${id}-line`;
+    this.labelLayerId = `${id}-label`;
+    this.map.on("style.load", this.handleStyleLoad);
+  }
+  /**
+   * Fetch and render reachability rings. Returns the GeoJSON
+   * FeatureCollection the gateway produced (each feature carries a
+   * `contour` property in minutes), for callers who also want the raw
+   * shapes. Replaces any rings already shown by this layer.
+   */
+  async showReachability(options) {
+    if (options.minutes.length === 0) {
+      throw new Error(
+        "showReachability needs at least one contour in minutes, e.g. { minutes: [5, 10, 15] }"
+      );
+    }
+    const [lon, lat] = toLngLat(options.origin);
+    const mode = options.mode ?? "walk";
+    const body = {
+      locations: [{ lat, lon }],
+      costing: MODE_TO_COSTING[mode] ?? mode,
+      // Largest first so smaller (nearer) rings paint on top.
+      contours: [...options.minutes].sort((a, b) => b - a).map((time) => ({ time })),
+      polygons: true
+    };
+    if (options.costingOptions) body["costing_options"] = options.costingOptions;
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json"
+    };
+    if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+    const response = await fetch(`${this.baseUrl}/isochrone`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      const problem = typeof payload === "object" && payload !== null ? payload : void 0;
+      const context = [problem?.["title"], problem?.["detail"]].filter((v) => typeof v === "string" && v.length > 0).join(" - ");
+      throw new Error(
+        `isochrone request failed: HTTP ${response.status}${context ? ` (${context})` : ""}`
+      );
+    }
+    if (typeof payload !== "object" || payload === null || payload["type"] !== "FeatureCollection") {
+      throw new Error("isochrone returned no FeatureCollection");
+    }
+    const collection = payload;
+    this.lastMinutes = [...options.minutes].sort((a, b) => a - b);
+    this.lastColor = options.color ?? SIGNAL_BLUE;
+    this.draw(collection);
+    return collection;
+  }
+  /** The most recently drawn rings, if any. */
+  get current() {
+    return this.lastData;
+  }
+  /** Draw (or update) a ring collection. Safe before the style has loaded. */
+  draw(collection) {
+    this.lastData = collection;
+    if (!this.map.isStyleLoaded()) return;
+    this.install(collection);
+  }
+  /** Add-or-update the source and ring layers on the current style. */
+  install(collection) {
+    const existing = this.map.getSource(this.sourceId);
+    if (existing) {
+      existing.setData(collection);
+    } else {
+      this.map.addSource(this.sourceId, {
+        type: "geojson",
+        data: collection
+      });
+    }
+    if (this.map.getLayer(this.fillLayerId)) {
+      this.map.setPaintProperty(
+        this.fillLayerId,
+        "fill-color",
+        this.lastColor
+      );
+      this.map.setPaintProperty(
+        this.fillLayerId,
+        "fill-opacity",
+        this.fillOpacity()
+      );
+      this.map.setPaintProperty(this.lineLayerId, "line-color", this.lastColor);
+      this.map.setPaintProperty(this.labelLayerId, "text-color", this.lastColor);
+      return;
+    }
+    const fill2 = {
+      id: this.fillLayerId,
+      type: "fill",
+      source: this.sourceId,
+      paint: {
+        "fill-color": this.lastColor,
+        "fill-opacity": this.fillOpacity()
+      }
+    };
+    const line = {
+      id: this.lineLayerId,
+      type: "line",
+      source: this.sourceId,
+      paint: {
+        "line-color": this.lastColor,
+        "line-width": 1.5,
+        "line-opacity": 0.8
+      }
+    };
+    const label = {
+      id: this.labelLayerId,
+      type: "symbol",
+      source: this.sourceId,
+      layout: {
+        "symbol-placement": "line",
+        "text-field": [
+          "concat",
+          ["to-string", ["get", "contour"]],
+          " min"
+        ],
+        // Ships with the MapMap default styles (see places.ts).
+        "text-font": ["Noto Sans Regular"],
+        "text-size": 11
+      },
+      paint: {
+        "text-color": this.lastColor,
+        "text-halo-color": "#ffffff",
+        "text-halo-width": 1.2
+      }
+    };
+    this.map.addLayer(fill2);
+    this.map.addLayer(line);
+    this.map.addLayer(label);
+  }
+  /**
+   * Graduated fill opacity: the nearest contour (fewest minutes) is the
+   * most opaque, the farthest the faintest, interpolated on each
+   * feature's `contour` property. With one contour it is a constant.
+   */
+  fillOpacity() {
+    const min = this.lastMinutes[0] ?? 0;
+    const max = this.lastMinutes[this.lastMinutes.length - 1] ?? 0;
+    if (this.lastMinutes.length < 2 || min === max) return 0.18;
+    return [
+      "interpolate",
+      ["linear"],
+      ["get", "contour"],
+      min,
+      0.28,
+      max,
+      0.08
+    ];
+  }
+  /** Remove the rings' layers and source from the map. */
+  clear() {
+    for (const layerId of [
+      this.labelLayerId,
+      this.lineLayerId,
+      this.fillLayerId
+    ]) {
+      if (this.map.getLayer(layerId)) this.map.removeLayer(layerId);
+    }
+    if (this.map.getSource(this.sourceId)) this.map.removeSource(this.sourceId);
+    this.lastData = void 0;
+  }
+  /** Remove the rings and detach the layer's `style.load` listener. */
+  destroy() {
+    this.map.off("style.load", this.handleStyleLoad);
+    this.clear();
+  }
+};
+
 // src/adr.ts
 function buildAdrCheckBody(request) {
   const dims = request.dimensions ?? {};
@@ -1763,14 +3338,14 @@ function directionArrow(direction) {
   }
 }
 function speak(instruction, options = {}) {
-  const synth = globalThis.speechSynthesis;
+  const synth2 = globalThis.speechSynthesis;
   const Utterance = globalThis.SpeechSynthesisUtterance;
-  if (!synth || !Utterance) return false;
+  if (!synth2 || !Utterance) return false;
   const text = instruction.ssmlAnnouncement ? ssmlToText(instruction.ssmlAnnouncement) : instruction.announcement;
   const utterance = new Utterance(text);
   if (options.lang) utterance.lang = options.lang;
   if (options.rate) utterance.rate = options.rate;
-  synth.speak(utterance);
+  synth2.speak(utterance);
   return true;
 }
 var GuidanceBanner = class {
@@ -1822,6 +3397,111 @@ var GuidanceBanner = class {
   }
 };
 
-export { AdrCheck, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, FULL_ATTRIBUTION, GuidanceBanner, LOGO_SVG, LogoControl, MAX_PUCK_IMAGE_BYTES, MapMapMap, NAV_CAMERA_DEFAULTS, NavigationCamera, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, PlacesLayer, PositionPuck, RouteLayer, SIGNAL_BLUE, SOURCE_LAYERS, bannerLanes, buildAdrCheckBody, buildRouteQuery, buildRouteUrl, buildStyle, createMap, defaultNavDesign, directionArrow, extractGuidance, formatCoord, formatCoords, haversineDistanceM, navDesignFromTheme, navDesignFromThemeUrl, parseNavDesign, parseOsrmRoute, placesFromGeoJSON, registerPmtilesProtocol, speak, ssmlToText, toLngLat, toPmtilesUrl };
+// src/voice.ts
+function severityProsody(severity, baseRate = 1) {
+  switch (severity) {
+    case "critical":
+      return { rate: baseRate * 1.1, pitch: 1.2, interrupt: true };
+    case "warning":
+      return { rate: baseRate, pitch: 1.1, interrupt: false };
+    default:
+      return { rate: baseRate, pitch: 1, interrupt: false };
+  }
+}
+var EARCON_SEVERITIES = ["warning", "critical"];
+var VoiceGuidance = class {
+  constructor(options = {}) {
+    this.offRouteAnnounced = false;
+    this.options = options;
+    this.volume = clampVolume(options.volume ?? 1);
+    this.mutedState = options.muted ?? false;
+  }
+  /** Whether this environment can speak at all. */
+  get available() {
+    return synth() !== void 0 && utteranceCtor() !== void 0;
+  }
+  /** Whether announcements are currently muted. */
+  get muted() {
+    return this.mutedState;
+  }
+  /** Mute announcements (also cancels anything mid-utterance). */
+  mute() {
+    this.mutedState = true;
+    synth()?.cancel();
+  }
+  /** Unmute announcements. Prompts seen while muted are not replayed. */
+  unmute() {
+    this.mutedState = false;
+  }
+  /** Set the volume for speech and earcons (clamped to 0–1). */
+  setVolume(volume) {
+    this.volume = clampVolume(volume);
+  }
+  /**
+   * Consume one guidance update. Speaks the update's prompt the first
+   * time its `utteranceId` appears; plays the warning earcon once per
+   * off-route episode. Safe to call in any environment.
+   */
+  update(update) {
+    if (update.state === "offRoute") {
+      if (!this.offRouteAnnounced) {
+        this.offRouteAnnounced = true;
+        this.playEarcon("warning");
+      }
+      return;
+    }
+    this.offRouteAnnounced = false;
+    const spoken = update.spoken;
+    if (!spoken || spoken.utteranceId === this.lastUtteranceId) return;
+    this.lastUtteranceId = spoken.utteranceId;
+    this.speak(spoken, update.severity ?? "info", update.voiceLocale);
+  }
+  /** Cancel any speech in progress and forget the de-duplication state. */
+  dispose() {
+    synth()?.cancel();
+    this.lastUtteranceId = void 0;
+    this.offRouteAnnounced = false;
+  }
+  speak(prompt, severity, voiceLocale) {
+    if (this.mutedState) return;
+    const synthesis = synth();
+    const Utterance = utteranceCtor();
+    if (!synthesis || !Utterance) return;
+    const prosody = severityProsody(severity, this.options.rate ?? 1);
+    if (prosody.interrupt) synthesis.cancel();
+    if (EARCON_SEVERITIES.includes(severity)) this.playEarcon(severity);
+    const text = prompt.ssml ? ssmlToText(prompt.ssml) : prompt.text;
+    const utterance = new Utterance(text);
+    const lang = voiceLocale ?? this.options.lang;
+    if (lang) utterance.lang = lang;
+    utterance.rate = prosody.rate;
+    utterance.pitch = prosody.pitch;
+    utterance.volume = this.volume;
+    synthesis.speak(utterance);
+  }
+  playEarcon(severity) {
+    if (this.mutedState) return;
+    const url = this.options.earcons?.[severity];
+    if (!url) return;
+    const AudioCtor = globalThis.Audio;
+    if (!AudioCtor) return;
+    const audio = new AudioCtor(url);
+    audio.volume = this.volume;
+    void audio.play()?.catch?.(() => {
+    });
+  }
+};
+function synth() {
+  return globalThis.speechSynthesis;
+}
+function utteranceCtor() {
+  return globalThis.SpeechSynthesisUtterance;
+}
+function clampVolume(volume) {
+  if (!Number.isFinite(volume)) return 1;
+  return Math.min(1, Math.max(0, volume));
+}
+
+export { AdrCheck, DEFAULT_GLYPHS_URL, DEFAULT_TERRITORY_TILES_URL, EFFECTS_METADATA_KEY, FLOW_DEFAULTS, FULL_ATTRIBUTION, FlowRouteEffectLayer, GuidanceBanner, IsochroneLayer, LOGO_SVG, LogoControl, MAX_PUCK_IMAGE_BYTES, MapMapMap, NAV_CAMERA_DEFAULTS, NavigationCamera, OPENMAPTILES_ATTRIBUTION, OSM_ATTRIBUTION, PALETTE_SLOTS, POI_CATEGORY_COLORS, POI_CATEGORY_IDS, POI_CLASS_CATEGORIES, PlacesLayer, PositionPuck, RIBBON_FLOATS_PER_VERTEX, ROUTE_EFFECTS, RouteLayer, SIGNAL_BLUE, SOURCE_LAYERS, ThemeScheduler, VoiceGuidance, applyPoiDesign, bannerLanes, bearingBetween, bindFlythroughToScroll, buildAdrCheckBody, buildProbeUrl, buildRouteQuery, buildRouteUrl, buildStyle, builtInPoiColor, createMap, createRouteEffect, defaultNavDesign, defaultPoiDesign, directionArrow, effectsFromStyleMetadata, extractGuidance, flythrough, flythroughPose, formatCoord, formatCoords, haversineDistanceM, isNameTextField, languageTextField, lngLatToMercator, navDesignFromTheme, navDesignFromThemeUrl, parseCssColour, parseNavDesign, parseOsrmRoute, parsePoiDesign, placesFromGeoJSON, poiDesignFromTheme, poiDesignFromThemeUrl, poiDesignIsDefault, poiTextColorExpression, prefersReducedMotion, registerPmtilesProtocol, resetDiagnostics, resolveTheme, runMapDiagnostics, setMapLanguage, severityProsody, shortestArcDeg, shortestArcDelta, speak, ssmlToText, sunTimes, tessellateRouteRibbon, toLngLat, toPmtilesUrl, uploadProbeBatch };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map