gloomberb 0.16.0 → 0.16.2

package/src/plugins/builtin/world-venue-map/feed.ts

@@ -0,0 +1,293 @@
+/**
+ * Features for the layers on the map. Each layer asks for what the view
+ * covers, waits for the view to settle before asking again, drops an answer a
+ * newer request replaced, refreshes on its own cadence while the pane can be
+ * seen, and asks nothing below its minimum zoom or while it is unavailable.
+ */
+import { ApiRequestError } from "../../../api-client/errors";
+import {
+  getGeoFeatures,
+  GEO_FEATURE_LIMIT,
+  type GeoCluster,
+  type GeoFeature,
+  type GeoLayerInfo,
+  type GeoRequest,
+} from "../../../api-client/geo";
+import { geoViewKey, MAX_RENDERED_CLUSTERS, MAX_RENDERED_FEATURES, type GeoView } from "./layers";
+
+type GeoLayerPhase = "loading" | "ready" | "error" | "zoom" | "unavailable" | "locked";
+
+export interface GeoLayerState {
+  layer: GeoLayerInfo;
+  phase: GeoLayerPhase;
+  /** Asking for a new view (or the first one); a timed refresh stays quiet. */
+  loading: boolean;
+  features: GeoFeature[];
+  clusters: GeoCluster[];
+  truncated: boolean;
+  asOf: string | null;
+  fetchedAt: number | null;
+  error: string | null;
+  /** The server's words for a layer that cannot serve right now. */
+  note: string | null;
+}
+
+interface Timers {
+  setTimeout: (callback: () => void, ms: number) => unknown;
+  clearTimeout: (handle: unknown) => void;
+  now: () => number;
+}
+
+interface FeedEntry {
+  state: GeoLayerState;
+  /** View the drawn features (or the request in flight) belong to. */
+  key: string | null;
+  controller: AbortController | null;
+  debounce: unknown;
+  refresh: unknown;
+  /** After a 429, nothing is asked before this time. */
+  blockedUntil: number;
+}
+
+export interface GeoFeedOptions {
+  debounceMs?: number;
+  timers?: Partial<Timers>;
+  /** Whether this viewer may read a layer; a Pro layer without Pro is drawn as locked. */
+  canAccess?: (layer: GeoLayerInfo) => boolean;
+}
+
+const DEFAULT_TIMERS: Timers = {
+  setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms),
+  clearTimeout: (handle) => globalThis.clearTimeout(handle as ReturnType<typeof setTimeout>),
+  now: () => Date.now(),
+};
+
+function isAbort(error: unknown): boolean {
+  return error instanceof DOMException ? error.name === "AbortError" : (error as { name?: string } | null)?.name === "AbortError";
+}
+
+export class GeoLayerFeed {
+  private readonly entries = new Map<string, FeedEntry>();
+  private readonly timers: Timers;
+  private readonly debounceMs: number;
+  private readonly canAccess: (layer: GeoLayerInfo) => boolean;
+  private view: GeoView | null = null;
+  private active = true;
+  private snapshotCache: GeoLayerState[] | null = null;
+
+  constructor(
+    private readonly request: GeoRequest,
+    private readonly onChange: () => void,
+    options: GeoFeedOptions = {},
+  ) {
+    this.timers = { ...DEFAULT_TIMERS, ...options.timers };
+    this.debounceMs = options.debounceMs ?? 250;
+    this.canAccess = options.canAccess ?? (() => true);
+  }
+
+  /** The layers on, in drawing order. */
+  snapshot(): GeoLayerState[] {
+    this.snapshotCache ??= [...this.entries.values()].map((entry) => entry.state);
+    return this.snapshotCache;
+  }
+
+  update(layers: readonly GeoLayerInfo[], view: GeoView, active: boolean): void {
+    const viewChanged = !this.view || geoViewKey(this.view) !== geoViewKey(view);
+    const resumed = active && !this.active;
+    this.view = view;
+    this.active = active;
+    const ids = new Set(layers.map((layer) => layer.id));
+    for (const [id, entry] of this.entries) {
+      if (ids.has(id)) continue;
+      this.stop(entry);
+      this.entries.delete(id);
+      this.changed();
+    }
+    for (const layer of layers) {
+      const existing = this.entries.get(layer.id);
+      const entry = existing ?? this.create(layer);
+      if (!existing) this.entries.set(layer.id, entry);
+      entry.state = { ...entry.state, layer };
+      this.plan(entry, view, { fresh: !existing, viewChanged, resumed });
+    }
+    this.reorder(layers);
+    this.changed();
+  }
+
+  /** Aborts and forgets everything; a later update starts over. */
+  dispose(): void {
+    for (const entry of this.entries.values()) this.stop(entry);
+    this.entries.clear();
+    this.view = null;
+    this.snapshotCache = null;
+  }
+
+  private create(layer: GeoLayerInfo): FeedEntry {
+    return {
+      state: { layer, phase: "loading", loading: false, features: [], clusters: [], truncated: false, asOf: layer.asOf, fetchedAt: null, error: null, note: null },
+      key: null,
+      controller: null,
+      debounce: null,
+      refresh: null,
+      blockedUntil: 0,
+    };
+  }
+
+  private reorder(layers: readonly GeoLayerInfo[]): void {
+    const ordered = layers.map((layer) => [layer.id, this.entries.get(layer.id)!] as const);
+    this.entries.clear();
+    for (const [id, entry] of ordered) this.entries.set(id, entry);
+  }
+
+  private plan(entry: FeedEntry, view: GeoView, change: { fresh: boolean; viewChanged: boolean; resumed: boolean }): void {
+    const { layer } = entry.state;
+    if (layer.status === "unavailable" || !this.canAccess(layer)) {
+      this.stop(entry);
+      entry.key = null;
+      entry.state = { ...entry.state, phase: layer.status === "unavailable" ? "unavailable" : "locked", loading: false, features: [], clusters: [], truncated: false, error: null };
+      return;
+    }
+    if (layer.minZoom !== undefined && view.zoom < layer.minZoom) {
+      this.stop(entry);
+      entry.key = null;
+      entry.state = { ...entry.state, phase: "zoom", loading: false, features: [], clusters: [], truncated: false, error: null };
+      return;
+    }
+    const key = geoViewKey(view);
+    if (!this.active) {
+      // Hidden: keep what is drawn, ask nothing, and catch up on return.
+      this.clearRefresh(entry);
+      return;
+    }
+    if (entry.key === key && !change.resumed) return;
+    if (entry.key === key && change.resumed) {
+      if (this.isDue(entry)) this.fetch(entry, key, true);
+      else this.scheduleRefresh(entry);
+      return;
+    }
+    // A new view supersedes whatever was in flight for the old one.
+    this.abort(entry);
+    this.clearRefresh(entry);
+    if (entry.debounce !== null) this.timers.clearTimeout(entry.debounce);
+    entry.debounce = null;
+    entry.key = key;
+    // A layer just turned on asks at once; a moving view waits until it settles.
+    if (change.fresh || !change.viewChanged) {
+      this.fetch(entry, key);
+      return;
+    }
+    entry.state = { ...entry.state, loading: true };
+    entry.debounce = this.timers.setTimeout(() => {
+      entry.debounce = null;
+      this.fetch(entry, key);
+    }, this.debounceMs);
+  }
+
+  private isDue(entry: FeedEntry): boolean {
+    const seconds = entry.state.layer.refreshSeconds;
+    if (!seconds || entry.state.fetchedAt === null) return entry.state.fetchedAt === null;
+    return this.timers.now() - entry.state.fetchedAt >= seconds * 1000;
+  }
+
+  private fetch(entry: FeedEntry, key: string, silent = false): void {
+    const view = this.view;
+    if (!view) return;
+    this.abort(entry);
+    this.clearRefresh(entry);
+    const wait = entry.blockedUntil - this.timers.now();
+    if (wait > 0) {
+      entry.refresh = this.timers.setTimeout(() => {
+        entry.refresh = null;
+        if (entry.key === key) this.fetch(entry, key, silent);
+      }, wait);
+      return;
+    }
+    const controller = new AbortController();
+    entry.controller = controller;
+    if (!silent || entry.state.fetchedAt === null) {
+      entry.state = { ...entry.state, loading: true, phase: entry.state.fetchedAt === null ? "loading" : entry.state.phase };
+      this.changed();
+    }
+    const layerId = entry.state.layer.id;
+    getGeoFeatures(this.request, layerId, { bbox: view.bbox, zoom: view.zoom, limit: GEO_FEATURE_LIMIT }, controller.signal)
+      .then((payload) => {
+        if (controller.signal.aborted || entry.controller !== controller || entry.key !== key) return;
+        entry.controller = null;
+        // A layer the catalog listed can still answer that it cannot serve (no positions yet).
+        if (payload.status === "unavailable") {
+          entry.state = { ...entry.state, phase: "unavailable", loading: false, features: [], clusters: [], truncated: false, fetchedAt: this.timers.now(), error: null, note: payload.statusNote ?? null };
+          this.scheduleRefresh(entry);
+          this.changed();
+          return;
+        }
+        entry.state = {
+          ...entry.state,
+          phase: "ready",
+          loading: false,
+          note: payload.status === "partial" ? payload.statusNote ?? null : null,
+          features: (payload.features ?? []).slice(0, MAX_RENDERED_FEATURES),
+          clusters: (payload.clusters ?? []).slice(0, MAX_RENDERED_CLUSTERS),
+          truncated: payload.truncated === true || (payload.features?.length ?? 0) > MAX_RENDERED_FEATURES,
+          asOf: payload.asOf ?? entry.state.layer.asOf,
+          fetchedAt: this.timers.now(),
+          error: null,
+        };
+        this.scheduleRefresh(entry);
+        this.changed();
+      })
+      .catch((error: unknown) => {
+        if (controller.signal.aborted || entry.controller !== controller || isAbort(error)) return;
+        entry.controller = null;
+        if (error instanceof ApiRequestError && error.status === 403) {
+          entry.state = { ...entry.state, phase: "locked", loading: false, features: [], clusters: [], truncated: false, error: null };
+          this.changed();
+          return;
+        }
+        // Keep drawn features through a failed refresh; the footer says it failed.
+        entry.state = {
+          ...entry.state,
+          phase: entry.state.fetchedAt === null ? "error" : entry.state.phase,
+          loading: false,
+          error: error instanceof Error ? error.message : String(error),
+        };
+        // Over the request limit: wait as long as the server asks before trying again.
+        const backoff = error instanceof ApiRequestError && error.status === 429 ? error.retryAfterMs ?? 30_000 : null;
+        if (backoff !== null) entry.blockedUntil = this.timers.now() + backoff;
+        this.scheduleRefresh(entry, backoff);
+        this.changed();
+      });
+  }
+
+  private scheduleRefresh(entry: FeedEntry, retryAfterMs: number | null = null): void {
+    this.clearRefresh(entry);
+    const seconds = entry.state.layer.refreshSeconds;
+    if ((!seconds && retryAfterMs === null) || !this.active) return;
+    const key = entry.key;
+    entry.refresh = this.timers.setTimeout(() => {
+      entry.refresh = null;
+      if (key && entry.key === key) this.fetch(entry, key, true);
+    }, Math.max(retryAfterMs ?? 0, (seconds ?? 0) * 1000));
+  }
+
+  private clearRefresh(entry: FeedEntry): void {
+    if (entry.refresh !== null) this.timers.clearTimeout(entry.refresh);
+    entry.refresh = null;
+  }
+
+  private abort(entry: FeedEntry): void {
+    entry.controller?.abort();
+    entry.controller = null;
+  }
+
+  private stop(entry: FeedEntry): void {
+    this.abort(entry);
+    this.clearRefresh(entry);
+    if (entry.debounce !== null) this.timers.clearTimeout(entry.debounce);
+    entry.debounce = null;
+  }
+
+  private changed(): void {
+    this.snapshotCache = null;
+    this.onChange();
+  }
+}

package/src/plugins/builtin/world-venue-map/geo-draw.tsx

@@ -0,0 +1,248 @@
+/**
+ * Geo layers on the world map: the model both renderers draw, the hit test
+ * they share, and the terminal's cells and bitmap. The desktop and web draw the
+ * same layers as SVG in `geo-svg.tsx`. Everything is placed with the venue
+ * map's own projection, so pan and zoom move the layers too.
+ */
+import type { GeoCluster, GeoFeature } from "../../../api-client/geo";
+import { drawCircle, drawLine, parseHex } from "../../../components/chart/native/raster/primitives";
+import type { NativeChartBitmap } from "../../../components/chart/native/chart-rasterizer";
+import { featureAnchor, featureLines } from "./layers";
+import { featureSymbol, MAP_SYMBOLS } from "./map-symbols";
+import type { WorldMapPoint } from "./model";
+
+export interface GeoMapLayer {
+  id: string;
+  name: string;
+  geometry: "point" | "line" | "area";
+  color: string;
+  features: readonly GeoFeature[];
+  clusters: readonly GeoCluster[];
+}
+
+export interface GeoMapSelection {
+  layerId: string;
+  id: string;
+  longitude: number;
+  latitude: number;
+}
+
+export interface GeoMapOverlay {
+  layers: readonly GeoMapLayer[];
+  selected: GeoMapSelection | null;
+  /** The selected entity's recent track, oldest first. */
+  trail: readonly (readonly [number, number])[] | null;
+}
+
+export type GeoHit =
+  | { kind: "feature"; layerId: string; feature: GeoFeature }
+  | { kind: "cluster"; layerId: string; cluster: GeoCluster };
+
+type Project = (longitude: number, latitude: number) => WorldMapPoint;
+
+/**
+ * Four hues as far apart as the map's four layers can be; green stays the
+ * venues'. Violet comes second so the layer beside ships never reads as their
+ * amber tankers.
+ */
+const DARK_PALETTE = ["#4dabf7", "#e599f7", "#ffa94d", "#ffe066"];
+const LIGHT_PALETTE = ["#1971c2", "#ae3ec9", "#d9480f", "#b08800"];
+
+/** The colour of the nth layer on the map, so the layers shown together never share one. */
+export function geoLayerColor(index: number, dark: boolean): string {
+  const palette = dark ? DARK_PALETTE : LIGHT_PALETTE;
+  return palette[((index % palette.length) + palette.length) % palette.length]!;
+}
+
+function distanceToSegment(point: WorldMapPoint, from: WorldMapPoint, to: WorldMapPoint): number {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const length = dx * dx + dy * dy;
+  const t = length === 0 ? 0 : Math.max(0, Math.min(1, ((point.x - from.x) * dx + (point.y - from.y) * dy) / length));
+  return Math.hypot(point.x - (from.x + t * dx), point.y - (from.y + t * dy));
+}
+
+function insideRing(point: WorldMapPoint, ring: readonly WorldMapPoint[]): boolean {
+  let inside = false;
+  for (let index = 0, previous = ring.length - 1; index < ring.length; previous = index, index += 1) {
+    const a = ring[index]!;
+    const b = ring[previous]!;
+    if ((a.y > point.y) !== (b.y > point.y) && point.x < ((b.x - a.x) * (point.y - a.y)) / (b.y - a.y) + a.x) inside = !inside;
+  }
+  return inside;
+}
+
+/** What sits under a point: a marker or cluster first, then a line, then an area. */
+export function hitTestGeo(
+  overlay: GeoMapOverlay,
+  point: WorldMapPoint,
+  project: Project,
+  maxDistance: number,
+): GeoHit | null {
+  let best: GeoHit | null = null;
+  let bestDistance = maxDistance;
+  for (const layer of overlay.layers) {
+    for (const cluster of layer.clusters) {
+      const at = project(cluster.lon, cluster.lat);
+      const distance = Math.hypot(at.x - point.x, at.y - point.y);
+      if (distance <= bestDistance) {
+        best = { kind: "cluster", layerId: layer.id, cluster };
+        bestDistance = distance;
+      }
+    }
+    if (layer.geometry !== "point") continue;
+    for (const feature of layer.features) {
+      const [longitude, latitude] = featureAnchor(feature);
+      const at = project(longitude, latitude);
+      const distance = Math.hypot(at.x - point.x, at.y - point.y);
+      if (distance <= bestDistance) {
+        best = { kind: "feature", layerId: layer.id, feature };
+        bestDistance = distance;
+      }
+    }
+  }
+  if (best) return best;
+  const lineDistance = maxDistance * 0.7;
+  bestDistance = lineDistance;
+  for (const layer of overlay.layers) {
+    if (layer.geometry !== "line") continue;
+    for (const feature of layer.features) {
+      for (const line of featureLines(feature)) {
+        for (let index = 1; index < line.length; index += 1) {
+          const from = project(line[index - 1]![0], line[index - 1]![1]);
+          const to = project(line[index]![0], line[index]![1]);
+          const distance = distanceToSegment(point, from, to);
+          if (distance <= bestDistance) {
+            best = { kind: "feature", layerId: layer.id, feature };
+            bestDistance = distance;
+          }
+        }
+      }
+    }
+  }
+  if (best) return best;
+  for (const layer of overlay.layers) {
+    if (layer.geometry !== "area") continue;
+    for (const feature of layer.features) {
+      const ring = featureLines(feature)[0];
+      if (ring && insideRing(point, ring.map(([longitude, latitude]) => project(longitude, latitude)))) {
+        return { kind: "feature", layerId: layer.id, feature };
+      }
+    }
+  }
+  return null;
+}
+
+/** A ship's class or a layer's icon as one terminal cell; anything unknown is a bullet. */
+export function cellGlyph(layerId: string, feature: GeoFeature): string {
+  const symbol = featureSymbol(layerId, feature);
+  if (symbol.id === "ship" || symbol.id === "ship-small" || symbol.id === "ship-other" || symbol.id === "ship-still") {
+    return SHIP_CELLS[symbol.tone] ?? "•";
+  }
+  return MAP_SYMBOLS[symbol.id].cell || "•";
+}
+
+const SHIP_CELLS: Partial<Record<string, string>> = {
+  tanker: "●",
+  layer: "■",
+  passenger: "○",
+  fishing: "▪",
+  service: "▫",
+  other: "•",
+};
+
+function cellLine(grid: string[][], from: WorldMapPoint, to: WorldMapPoint, glyph: string) {
+  const steps = Math.max(1, Math.ceil(Math.max(Math.abs(to.x - from.x), Math.abs(to.y - from.y))));
+  for (let step = 0; step <= steps; step += 1) {
+    const x = Math.round(from.x + ((to.x - from.x) * step) / steps);
+    const y = Math.round(from.y + ((to.y - from.y) * step) / steps);
+    const row = grid[y];
+    if (!row || x < 0 || x >= row.length) continue;
+    if (row[x] === " " || row[x] === ".") row[x] = glyph;
+  }
+}
+
+/**
+ * The terminal's reduced map: lines and area edges as dots, markers as their
+ * icon's cell glyph (a ship's by its class), clusters as their count (`+` past
+ * nine), the selection as `@`.
+ */
+export function rasterGeoCells(grid: string[][], overlay: GeoMapOverlay, project: Project): void {
+  for (const layer of overlay.layers) {
+    if (layer.geometry === "point") continue;
+    for (const feature of layer.features) {
+      for (const line of featureLines(feature)) {
+        for (let index = 1; index < line.length; index += 1) {
+          const previous = line[index - 1]!;
+          const current = line[index]!;
+          if (Math.abs(current[0] - previous[0]) > 180) continue;
+          cellLine(grid, project(previous[0], previous[1]), project(current[0], current[1]), layer.geometry === "area" ? "░" : "·");
+        }
+      }
+    }
+  }
+  if (overlay.trail) {
+    for (let index = 1; index < overlay.trail.length; index += 1) {
+      cellLine(grid, project(overlay.trail[index - 1]![0], overlay.trail[index - 1]![1]), project(overlay.trail[index]![0], overlay.trail[index]![1]), "·");
+    }
+  }
+  const place = (longitude: number, latitude: number, glyph: string) => {
+    const at = project(longitude, latitude);
+    const row = grid[Math.round(at.y)];
+    const x = Math.round(at.x);
+    if (row && x >= 0 && x < row.length) row[x] = glyph;
+  };
+  for (const layer of overlay.layers) {
+    if (layer.geometry !== "point") continue;
+    for (const feature of layer.features) {
+      const [longitude, latitude] = featureAnchor(feature);
+      place(longitude, latitude, cellGlyph(layer.id, feature));
+    }
+  }
+  for (const layer of overlay.layers) {
+    for (const cluster of layer.clusters) place(cluster.lon, cluster.lat, cluster.count > 9 ? "+" : String(cluster.count));
+  }
+  if (overlay.selected) place(overlay.selected.longitude, overlay.selected.latitude, "@");
+}
+
+/** The same layers on a terminal that draws pixels. */
+export function drawGeoBitmap(bitmap: NativeChartBitmap, overlay: GeoMapOverlay, project: Project, selectedColor: string): void {
+  const thickness = Math.max(1, bitmap.width / 700);
+  for (const layer of overlay.layers) {
+    const color = parseHex(layer.color, layer.geometry === "area" ? 0.7 : 0.95);
+    if (layer.geometry === "point") {
+      for (const feature of layer.features) {
+        const [longitude, latitude] = featureAnchor(feature);
+        const at = project(longitude, latitude);
+        drawCircle(bitmap.pixels, bitmap.width, bitmap.height, at.x, at.y, Math.max(1.5, thickness * 1.6), color);
+      }
+    } else {
+      for (const feature of layer.features) {
+        for (const line of featureLines(feature)) {
+          for (let index = 1; index < line.length; index += 1) {
+            if (Math.abs(line[index]![0] - line[index - 1]![0]) > 180) continue;
+            const from = project(line[index - 1]![0], line[index - 1]![1]);
+            const to = project(line[index]![0], line[index]![1]);
+            drawLine(bitmap.pixels, bitmap.width, bitmap.height, from.x, from.y, to.x, to.y, color, thickness);
+          }
+        }
+      }
+    }
+    for (const cluster of layer.clusters) {
+      const at = project(cluster.lon, cluster.lat);
+      drawCircle(bitmap.pixels, bitmap.width, bitmap.height, at.x, at.y, Math.max(3, Math.min(12, 2.5 + Math.sqrt(cluster.count) * 0.9)), parseHex(layer.color, 0.9));
+    }
+  }
+  const highlight = parseHex(selectedColor);
+  if (overlay.trail) {
+    for (let index = 1; index < overlay.trail.length; index += 1) {
+      const from = project(overlay.trail[index - 1]![0], overlay.trail[index - 1]![1]);
+      const to = project(overlay.trail[index]![0], overlay.trail[index]![1]);
+      drawLine(bitmap.pixels, bitmap.width, bitmap.height, from.x, from.y, to.x, to.y, highlight, thickness);
+    }
+  }
+  if (overlay.selected) {
+    const at = project(overlay.selected.longitude, overlay.selected.latitude);
+    drawCircle(bitmap.pixels, bitmap.width, bitmap.height, at.x, at.y, Math.max(4, thickness * 4), highlight);
+  }
+}

package/src/plugins/builtin/world-venue-map/geo-series.ts

@@ -0,0 +1,142 @@
+/**
+ * Map series in G: numbers over time for things with a place (chokepoint
+ * transits, port calls). `GEO:<id or alias>` resolves through the server's
+ * series index, so a series the server adds is chartable without a release.
+ */
+import {
+  getGeoSeries,
+  loadGeoCatalog,
+  resolveGeoSeries,
+  searchGeoSeries,
+  type GeoRequest,
+  type GeoSeriesSearchHit,
+} from "../../../api-client/geo";
+import { chartSeriesProvider, type ChartSeriesCapability, type ChartSeriesCatalogItem } from "../../../capabilities";
+import { subtractTimeRange } from "../../../time-series/date-window";
+import { SERIES_COLORS } from "../../../time-series/resolve";
+import type { ChartViewportSpec, ResolvedSeries, TimeSeriesPoint } from "../../../time-series/types";
+import { GEO_SERIES_CAPABILITY_ID } from "../chart-composer/series-expression";
+import { cloudGeoRequest } from "./client";
+
+function catalogItem(hit: GeoSeriesSearchHit): ChartSeriesCatalogItem {
+  return {
+    seriesId: hit.alias ?? hit.id,
+    label: hit.name,
+    detail: `${hit.unit} · ${hit.frequency}`,
+    style: "line",
+  };
+}
+
+/** A capability series brings its own colour; one per id keeps two map series apart on one chart. */
+function seriesColor(id: string): string {
+  let hash = 0;
+  for (const char of id) hash = (hash * 31 + char.charCodeAt(0)) >>> 0;
+  return SERIES_COLORS[hash % SERIES_COLORS.length]!;
+}
+
+function isoDate(date: Date): string {
+  return date.toISOString().slice(0, 10);
+}
+
+/** The dates a viewport asks for, as the series route takes them. */
+export function geoSeriesRange(viewport: ChartViewportSpec, now = new Date()): { from?: string; to?: string } {
+  if (viewport.dateWindow) {
+    return { from: viewport.dateWindow.start.slice(0, 10), to: viewport.dateWindow.end.slice(0, 10) };
+  }
+  if (viewport.range === "ALL") return {};
+  return { from: isoDate(subtractTimeRange(now, viewport.range)) };
+}
+
+export async function resolveGeoChartSeries(
+  request: GeoRequest,
+  token: string,
+  viewport: ChartViewportSpec,
+  signal?: AbortSignal,
+): Promise<ResolvedSeries> {
+  const hit = await resolveGeoSeries(request, token, signal).catch(() => null);
+  const payload = await getGeoSeries(request, hit?.id ?? token, geoSeriesRange(viewport), signal).catch((error: unknown) => {
+    throw hit ? error : new Error(`No map series named ${token}.`);
+  });
+  const points: TimeSeriesPoint[] = (payload.points ?? []).flatMap(([day, value]) => {
+    const date = new Date(`${day}T00:00:00Z`);
+    return Number.isFinite(date.getTime()) && Number.isFinite(value) ? [{ date, observedAt: date, value }] : [];
+  });
+  return {
+    id: `${GEO_SERIES_CAPABILITY_ID}:${payload.id}`,
+    label: payload.name,
+    color: seriesColor(payload.id),
+    unit: payload.unit,
+    unitGroup: `geo:${payload.unit}`,
+    nativeFrequency: payload.frequency,
+    dataShape: "scalar",
+    style: "line",
+    transform: "raw",
+    axis: "left",
+    panelId: "main",
+    interpolation: "none",
+    points,
+  };
+}
+
+export function createGeoChartSeriesCapability(request: GeoRequest = cloudGeoRequest): ChartSeriesCapability {
+  const search = async (query: string, limit: number, signal?: AbortSignal) => {
+    const { series } = await searchGeoSeries(request, query, signal).catch(() => ({ series: [] as GeoSeriesSearchHit[] }));
+    return series.slice(0, limit).map(catalogItem);
+  };
+  return chartSeriesProvider({
+    id: GEO_SERIES_CAPABILITY_ID,
+    name: "Map Series",
+    provider: {
+      catalog: ({ limit, signal }) => search("", limit ?? 8, signal),
+      search: ({ query, limit, signal }) => search(query ?? "", limit ?? 8, signal),
+      resolve: ({ seriesId, viewport, signal }) => resolveGeoChartSeries(request, seriesId, viewport, signal),
+    },
+  });
+}
+
+const CHOKEPOINTS_LAYER = "chokepoints";
+
+function compact(value: string): string {
+  return value.toUpperCase().replace(/[^A-Z0-9.]+/g, "");
+}
+
+/**
+ * The straits trade and oil markets watch, in the order CHOKE charts them.
+ * The busiest by count are local Asian straits, which say less about trade.
+ */
+export const KEY_CHOKEPOINTS = ["SUEZ", "PANAMA", "HORMUZ", "BABELMANDEB", "MALACCA", "BOSPHORUS"];
+
+/**
+ * CHOKE's series as the short aliases G takes: the key straits the index
+ * has, else the chokepoints' main series as the catalog lists them.
+ */
+export async function chokepointSeriesIds(request: GeoRequest, signal?: AbortSignal): Promise<string[]> {
+  const [catalog, { series }] = await Promise.all([loadGeoCatalog(request, { signal }), searchGeoSeries(request, "", signal)]);
+  const known = new Set(series.filter((hit) => hit.layer === CHOKEPOINTS_LAYER && hit.alias).map((hit) => hit.alias!.toUpperCase()));
+  const key = KEY_CHOKEPOINTS.filter((alias) => known.has(alias));
+  if (key.length >= 3) return key;
+  const aliasById = new Map(series.map((hit) => [hit.id, hit.alias]));
+  const main = catalog?.layers.find((layer) => layer.id === CHOKEPOINTS_LAYER)?.series ?? [];
+  if (main.length) return main.map((entry) => aliasById.get(entry.id) ?? entry.id);
+  // Without the catalog, one series per chokepoint: the first the index lists.
+  const seen = new Set<string>();
+  return series.flatMap((hit) => {
+    if (hit.layer !== CHOKEPOINTS_LAYER || !hit.entityId || seen.has(hit.entityId)) return [];
+    seen.add(hit.entityId);
+    return [hit.alias ?? hit.id];
+  });
+}
+
+/**
+ * The series a typed chokepoint names: "suez", "Bab el-Mandeb" and "Strait
+ * of Hormuz" all find the strait's main transit series.
+ */
+export async function chokepointSeriesFor(request: GeoRequest, typed: string, signal?: AbortSignal): Promise<string> {
+  const wanted = compact(typed);
+  const { series } = await searchGeoSeries(request, typed, signal).catch(() => ({ series: [] as GeoSeriesSearchHit[] }));
+  const chokepoints = series.filter((hit) => hit.layer === CHOKEPOINTS_LAYER);
+  const exact = chokepoints.find((hit) => hit.alias && compact(hit.alias) === wanted);
+  // A main transit series has the plain alias (SUEZ), its splits a suffix (SUEZ.TANKER).
+  const named = chokepoints.find((hit) => hit.alias && !hit.alias.includes("."));
+  return exact?.alias ?? named?.alias ?? wanted;
+}