gloomberb 0.16.1 → 0.16.2

package/src/plugins/builtin/ticker-detail/index.tsx

@@ -85,6 +85,7 @@ export const tickerDetailModule: PluginModule = {
     },
     {
       id: "returns",
+      reportFreshness: { status: "not-a-feed", basis: "price history" },
       name: "Returns",
       icon: "R",
       component: ReturnsPane,

package/src/plugins/builtin/ticker-detail/overview/model.ts

@@ -72,6 +72,7 @@ export function buildOverviewStats({
   baseCurrency,
   marketCapExchangeRates = new Map(),
   nextEarnings,
+  depositaryReceipt = false,
   today,
 }: {
   quote: Quote | undefined;
@@ -81,6 +82,8 @@ export function buildOverviewStats({
   toBase: CurrencyConverter;
   marketCapExchangeRates?: ReadonlyMap<string, number>;
   nextEarnings?: NextEarnings;
+  /** The listing is a depositary receipt, so its share count is in receipts. */
+  depositaryReceipt?: boolean;
   /** The listing's calendar day, YYYY-MM-DD; dates before it are left out. */
   today?: string;
 }): StatField[] {
@@ -105,7 +108,11 @@ export function buildOverviewStats({
     });
   }
   if (fundamentals?.sharesOutstanding) {
-    stats.push({ label: "Shares Out", value: formatCompact(fundamentals.sharesOutstanding) });
+    stats.push({
+      label: "Shares Out",
+      value: formatCompact(fundamentals.sharesOutstanding),
+      ...(depositaryReceipt ? { detail: ["ADR equivalent", "in ADRs"] } : {}),
+    });
   }
   if (finite(fundamentals?.floatShares) && fundamentals.floatShares > 0) {
     stats.push({ label: "Float", value: formatCompact(fundamentals.floatShares) });
@@ -122,7 +129,7 @@ export function buildOverviewStats({
     stats.push({ label: "EPS", value: money(fundamentals.eps, true) });
   }
   if (fundamentals?.pegRatio != null) {
-    stats.push({ label: "PEG", value: formatNumber(fundamentals.pegRatio, 2) });
+    stats.push({ label: "PEG", value: formatPriceEarnings(fundamentals.pegRatio, 2) });
   }
   // A report the payload still lists after its day has passed is not the next one.
   if (today && nextEarnings && ISO_DATE.test(nextEarnings.date) && nextEarnings.date >= today) {

package/src/plugins/builtin/ticker-detail/overview-tab.tsx

@@ -8,7 +8,13 @@ import { PriceReturnStrip } from "../../../components/price-performance";
 import { t } from "../../../i18n";
 import { useFxRatesMap } from "../../../market-data/hooks";
 import { formatMarketPriceWithCurrency, formatSignedMarketPrice, liveQuoteFormatOptions } from "../../../market-data/market/format";
-import { exchangeShortName, marketStateColor, marketStateLabel } from "../../../market-data/market/status";
+import {
+  exchangeShortName,
+  getExtendedSessionDisplay,
+  getRegularSessionDisplay,
+  marketStateColor,
+  marketStateLabel,
+} from "../../../market-data/market/status";
 import { appendQuoteToPriceReturnHistory, buildPriceReturnFields } from "../../../market-data/performance";
 import { useViewport } from "../../../react/input";
 import { useAppSelector } from "../../../state/app/context";
@@ -20,6 +26,7 @@ import { Box, ScrollBox, Text, useUiCapabilities } from "../../../ui";
 import { publicTickerKey, resolveExchangeTimeZone } from "../../../utils/exchanges";
 import { convertCurrency, displayWidth, formatPercentRaw, truncateToDisplayWidth } from "../../../utils/format";
 import { zonedDateKey } from "../../../utils/zoned-date-time";
+import { isDepositaryReceipt } from "../../../utils/depositary-receipt";
 import {
   CompactRangeBar,
   FundamentalsGrid,
@@ -131,9 +138,12 @@ function ResolvedOverviewTab({ width, focused = false, ticker, financials, onOpe
   const quoteSummaryWidth = quoteBookInline ? Math.max(20, contentWidth - quoteBookWidth - 2) : contentWidth;
   // Price, change and ranges keep the instrument's decimals on every streamed tick.
   const moneyOptions = liveQuoteFormatOptions(quote, quote?.currency, ticker.metadata.assetCategory, financials?.quoteMetadata?.instrumentType);
-  const quotePriceText = quote ? formatMarketPriceWithCurrency(quote.price, quote.currency, moneyOptions) : "";
-  const quoteChangeText = quote ? formatSignedMarketPrice(quote.change, moneyOptions) : "";
-  const quotePercentText = quote ? `(${formatPercentRaw(quote.changePercent)})` : "";
+  // The headline is the regular session, which stops at the close; extended trading is the line below it.
+  const sessionQuote = getRegularSessionDisplay(quote);
+  const extendedQuote = getExtendedSessionDisplay(quote);
+  const quotePriceText = sessionQuote ? formatMarketPriceWithCurrency(sessionQuote.price, quote?.currency, moneyOptions) : "";
+  const quoteChangeText = sessionQuote ? formatSignedMarketPrice(sessionQuote.change, moneyOptions) : "";
+  const quotePercentText = sessionQuote ? `(${formatPercentRaw(sessionQuote.changePercent)})` : "";
   // The pane title already names the ticker, so the line leads with the company and drops a name that only repeats it.
   const companyName = [ticker.metadata.name, quote?.name].find((name) => name && name !== ticker.metadata.ticker) ?? "";
   const venueText = listingVenue ? (companyName ? ` (${listingVenue})` : listingVenue) : "";
@@ -184,6 +194,7 @@ function ResolvedOverviewTab({ width, focused = false, ticker, financials, onOpe
     toBase,
     marketCapExchangeRates: exchangeRates,
     nextEarnings: financials?.nextEarnings,
+    depositaryReceipt: isDepositaryReceipt({ ...quote, description }),
     // Report and ex-dividend dates are the listing's calendar days.
     today: zonedDateKey(Date.now(), chartTimeZone ?? "America/New_York"),
   });
@@ -241,7 +252,7 @@ function ResolvedOverviewTab({ width, focused = false, ticker, financials, onOpe
               </Box>
             )}
 
-            {quote && (
+            {sessionQuote && (
               <Box
                 flexDirection={stackQuoteSummary ? "column" : "row"}
                 gap={stackQuoteSummary ? 0 : 2}
@@ -249,30 +260,19 @@ function ResolvedOverviewTab({ width, focused = false, ticker, financials, onOpe
               >
                 <FigureText>{quotePriceText}</FigureText>
                 <Box flexDirection={stackQuoteChange ? "column" : "row"} gap={stackQuoteChange ? 0 : 1}>
-                  <FigureText part="sub" change={quote.change}>{quoteChangeText}</FigureText>
-                  <FigureText part="sub" change={quote.change}>{quotePercentText}</FigureText>
+                  <FigureText part="sub" change={sessionQuote.change}>{quoteChangeText}</FigureText>
+                  <FigureText part="sub" change={sessionQuote.change}>{quotePercentText}</FigureText>
                 </Box>
               </Box>
             )}
-            {quote && (quote.marketState === "PRE" || quote.marketState === "PREPRE") && quote.preMarketPrice != null && (
-              <Box flexDirection="row" gap={2}>
-                <Text fg={colors.textDim}>{t("Pre-Market")}:</Text>
-                <Text fg={priceColor(quote.preMarketChange ?? 0)}>
-                  {formatMarketPriceWithCurrency(quote.preMarketPrice, quote.currency, moneyOptions)}
-                </Text>
-                <Text fg={priceColor(quote.preMarketChange ?? 0)}>
-                  {formatSignedMarketPrice(quote.preMarketChange, moneyOptions)} ({formatPercentRaw(quote.preMarketChangePercent)})
-                </Text>
-              </Box>
-            )}
-            {quote && (quote.marketState === "POST" || quote.marketState === "POSTPOST") && quote.postMarketPrice != null && (
+            {extendedQuote && (
               <Box flexDirection="row" gap={2}>
-                <Text fg={colors.textDim}>{t("After-Hours")}:</Text>
-                <Text fg={priceColor(quote.postMarketChange ?? 0)}>
-                  {formatMarketPriceWithCurrency(quote.postMarketPrice, quote.currency, moneyOptions)}
+                <Text fg={colors.textDim}>{extendedQuote.session === "PRE" ? t("Pre-Market") : t("After-Hours")}:</Text>
+                <Text fg={priceColor(extendedQuote.change ?? 0)}>
+                  {formatMarketPriceWithCurrency(extendedQuote.price, quote?.currency, moneyOptions)}
                 </Text>
-                <Text fg={priceColor(quote.postMarketChange ?? 0)}>
-                  {formatSignedMarketPrice(quote.postMarketChange, moneyOptions)} ({formatPercentRaw(quote.postMarketChangePercent)})
+                <Text fg={priceColor(extendedQuote.change ?? 0)}>
+                  {formatSignedMarketPrice(extendedQuote.change, moneyOptions)} ({formatPercentRaw(extendedQuote.changePercent)})
                 </Text>
               </Box>
             )}
@@ -293,7 +293,7 @@ function ResolvedOverviewTab({ width, focused = false, ticker, financials, onOpe
           <Box flexDirection={rangeInline ? "row" : "column"} gap={rangeInline ? RANGE_PAIR_GAP : 0} width={contentWidth}>
             {hasDayRange && (
               <CompactRangeBar
-                current={quote.price}
+                current={sessionQuote?.price ?? quote.price}
                 low={quote.low!}
                 high={quote.high!}
                 label={dayRangeLabel}
@@ -307,7 +307,7 @@ function ResolvedOverviewTab({ width, focused = false, ticker, financials, onOpe
             )}
             {yearRange && (
               <CompactRangeBar
-                current={quote.price}
+                current={sessionQuote?.price ?? quote.price}
                 low={yearRange.low}
                 high={yearRange.high}
                 label={yearRangeLabel}

package/src/plugins/builtin/time-sales/headless.ts

@@ -29,7 +29,11 @@ export const timeSalesHeadless: HeadlessPaneDefinition<"bundle"> = {
     // One decimal count per column, as the pane shows it, so sub-penny prints align.
     const price = fixedPrice(tapePriceDigits(data.trades.map((row) => row.price)));
     const trades = newestFirst(data.trades).slice(0, Number(args.options.limit ?? 100)).map((row) => ({ ...row, conditions: row.conditions.join(" ") }));
-    return { sections: [
+    // SIP prints, real-time or fifteen minutes delayed by entitlement, dated by the newest print.
+    const freshness = data.feed === "sip"
+      ? { status: "live" as const, cadence: "daily" as const }
+      : { status: "delayed" as const, delayMinutes: Math.round(data.delaySeconds / 60), cadence: "daily" as const };
+    return { freshness, sections: [
       { title: "Observed window", columns: formattedColumns(window, { vwap: price, low: price, high: price }), rows: window },
       { title: "Regular session", columns: formattedColumns([data.session], { high: price, low: price }), rows: [data.session] },
       { title: "Trades", columns: formattedColumns(trades, { price }), rows: trades },

package/src/plugins/builtin/treasury-auctions/headless.ts

@@ -40,6 +40,7 @@ function createTreasuryAuctionsHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
+    freshness: { source: "US Treasury", status: "not-a-feed", basis: "auction results", observedKey: "auctionDate", oldest: null },
     argument: {
       kind: "free-text",
       placeholder: "search",

package/src/plugins/builtin/volatility/headless.ts

@@ -1,6 +1,7 @@
 import type { HeadlessBundleResult, HeadlessPaneContext, HeadlessPaneDefinition, HeadlessPaneLoadArgs } from "../../../types/plugin";
 import { createVolatilityDependencies, loadVolatilityData, type VolatilityLoadResult } from "./client";
 import type { VolatilityData } from "./model";
+import { newestReportTime, oldestReportTime } from "../../../utils/utc-time";
 
 function formattedValue(value: unknown): string { return typeof value === "number" && Number.isFinite(value) ? value.toFixed(2) : "--"; }
 function formattedPercentile(value: unknown): string { return typeof value === "number" && Number.isFinite(value) ? value.toFixed(0) : "--"; }
@@ -53,7 +54,11 @@ export function createVolatilityHeadless(dependencies: VolatilityHeadlessDepende
     async load(args, context) {
       const result = await dependencies.load(args, context);
       context.signal.throwIfAborted();
-      return { ...projectVolatilityHeadless(result.data), errors: result.errors,
+      // Daily index closes, dated by the newest index on the board; a sparse index shows as the oldest.
+      const boardDates = result.data.board.filter((row) => row.value != null).map((row) => row.date);
+      const freshness = { source: "Cboe and FRED", status: "not-a-feed" as const, basis: "daily index closes", cadence: "daily" as const,
+        asOf: newestReportTime([...boardDates, result.data.curve.date]), oldest: oldestReportTime(boardDates) };
+      return { ...projectVolatilityHeadless(result.data), freshness, errors: result.errors,
         complete: result.phase === "ready" && !result.stale && result.data.warnings.length === 0,
         unavailableSymbols: result.data.board.filter((row) => row.value == null).map((row) => row.symbol),
         metadata: { stale: result.stale, phase: result.phase, loaded: result.loaded, total: result.total,

package/src/plugins/builtin/world-indices/headless.ts

@@ -15,6 +15,7 @@ import {
   WORLD_INDICES,
   type IndexEntry,
 } from "./indices";
+import { quoteFreshnessFields } from "../shared/report-freshness";
 
 const COLUMNS = [
   { key: "shortName", header: "Index" },
@@ -69,6 +70,7 @@ function projectWorldIndicesHeadless(
         rows: regionEntries.map((entry) => {
           const quote = loaded.quotes.get(entry.symbol);
           return {
+            ...quoteFreshnessFields(quote),
             ...entry,
             price: quote?.price ?? null,
             unit: "index points",

package/src/plugins/builtin/world-venue-map/basemap-layer.tsx

@@ -0,0 +1,157 @@
+/**
+ * The land under the desktop and web map: a quiet fill, 1 px coastlines and
+ * fainter borders, at 1:50m for the world and 1:10m for the tiles in view once
+ * zoomed in. Until a level arrives the level below stands in for it: the
+ * terminal's outline before the 1:50m chunk, 1:50m over tiles still loading.
+ */
+import { memo, useEffect, useId, useMemo, useState } from "react";
+import {
+  basemapLevel,
+  GRATICULE_MAX_PX_PER_DEGREE,
+  loadDetailIndex,
+  loadDetailTile,
+  loadWorldBasemap,
+  TILE_CACHE_SIZE,
+  tilesInView,
+  type BasemapPaths,
+  type DetailTile,
+  type GeoBox,
+} from "./basemap";
+import { matrixTransform, type MapMatrix } from "./geo-svg";
+import { WORLD_OUTLINES } from "./world-outlines";
+
+export interface BasemapPalette {
+  land: string;
+  coast: string;
+  border: string;
+}
+
+interface BasemapLayerProps {
+  matrix: MapMatrix;
+  view: GeoBox;
+  pxPerDegree: number;
+  palette: BasemapPalette;
+}
+
+let outlinePath: BasemapPaths | null = null;
+
+/** The terminal's 1:110m outlines in degrees, shown for the moment before 1:50m arrives. */
+function fallbackPaths(): BasemapPaths {
+  if (outlinePath) return outlinePath;
+  let land = "";
+  for (const outline of WORLD_OUTLINES) {
+    let previous: number | null = null;
+    for (const [longitude, latitude] of outline) {
+      const lat = Math.max(-60, latitude);
+      land += `${previous === null || Math.abs(longitude - previous) > 180 ? "M" : "L"}${longitude} ${-lat}`;
+      previous = longitude;
+    }
+  }
+  outlinePath = { land: "", coast: land, borders: "" };
+  return outlinePath;
+}
+
+const GRATICULE = (() => {
+  let path = "";
+  for (let longitude = -180; longitude <= 180; longitude += 30) path += `M${longitude} 60L${longitude} -85`;
+  for (let latitude = -30; latitude <= 60; latitude += 30) path += `M-180 ${-latitude}L180 ${-latitude}`;
+  return path;
+})();
+
+function useWorldPaths(): BasemapPaths | null {
+  const [paths, setPaths] = useState<BasemapPaths | null>(null);
+  useEffect(() => {
+    let current = true;
+    loadWorldBasemap().then((loaded) => {
+      if (current) setPaths(loaded);
+    }, () => {});
+    return () => {
+      current = false;
+    };
+  }, []);
+  return paths;
+}
+
+function useDetailTiles(active: boolean, view: GeoBox): { tiles: DetailTile[]; loaded: ReadonlyMap<string, BasemapPaths> } {
+  const [index, setIndex] = useState<readonly DetailTile[] | null>(null);
+  const [loaded, setLoaded] = useState<ReadonlyMap<string, BasemapPaths>>(() => new Map());
+  useEffect(() => {
+    if (!active || index) return;
+    let current = true;
+    loadDetailIndex().then((tiles) => {
+      if (current) setIndex(tiles);
+    }, () => {});
+    return () => {
+      current = false;
+    };
+  }, [active, index]);
+  const tiles = active && index ? tilesInView(index, view) : [];
+  const key = tiles.map((tile) => tile.id).join(",");
+  useEffect(() => {
+    if (!key || !index) return;
+    let current = true;
+    for (const tile of index.filter((entry) => key.split(",").includes(entry.id))) {
+      loadDetailTile(tile).then((paths) => {
+        if (!current) return;
+        setLoaded((previous) => {
+          if (previous.get(tile.id) === paths) return previous;
+          // Newest last; the map keeps no more decoded tiles than the cache does.
+          const next = new Map(previous);
+          next.delete(tile.id);
+          next.set(tile.id, paths);
+          while (next.size > TILE_CACHE_SIZE) next.delete(next.keys().next().value!);
+          return next;
+        });
+      }, () => {});
+    }
+    return () => {
+      current = false;
+    };
+  }, [index, key]);
+  return useMemo(() => ({ tiles, loaded }), [key, loaded]);
+}
+
+const BasemapPathsView = memo(function BasemapPathsView({ paths, palette, clipPath }: { paths: BasemapPaths; palette: BasemapPalette; clipPath?: string }) {
+  return (
+    <g clipPath={clipPath}>
+      {paths.land ? <path d={paths.land} fill={palette.land} fillRule="evenodd" stroke="none" /> : null}
+      {paths.borders ? (
+        <path d={paths.borders} fill="none" stroke={palette.border} strokeWidth={0.7} strokeLinejoin="round" vectorEffect="non-scaling-stroke" />
+      ) : null}
+      {paths.coast ? <path d={paths.coast} fill="none" stroke={palette.coast} strokeWidth={1} strokeLinejoin="round" vectorEffect="non-scaling-stroke" /> : null}
+    </g>
+  );
+});
+
+export function BasemapLayer({ matrix, view, pxPerDegree, palette }: BasemapLayerProps) {
+  const clipId = `gloom-basemap-${useId().replace(/[^a-zA-Z0-9_-]/g, "")}`;
+  const world = useWorldPaths();
+  const level = basemapLevel(pxPerDegree);
+  const { tiles, loaded } = useDetailTiles(level === "detail", view);
+  const ready = tiles.filter((tile) => loaded.has(tile.id));
+  const missing = tiles.filter((tile) => !loaded.has(tile.id));
+  // While tiles load, 1:50m fills in only where they are missing.
+  const partial = level === "detail" && missing.length > 0 && ready.length > 0;
+  const showWorld = level === "world" || !tiles.length || missing.length > 0;
+  return (
+    <g
+      transform={matrixTransform(matrix)}
+      data-gloom-role="basemap"
+      data-basemap-level={level === "detail" && tiles.length && !missing.length ? "detail" : world ? "world" : "outline"}
+    >
+      {pxPerDegree <= GRATICULE_MAX_PX_PER_DEGREE ? (
+        <path d={GRATICULE} fill="none" stroke={palette.border} strokeOpacity={0.45} strokeWidth={0.5} vectorEffect="non-scaling-stroke" />
+      ) : null}
+      {partial ? (
+        <defs>
+          <clipPath id={clipId}>
+            {missing.map((tile) => <rect key={tile.id} x={tile.box[0]} y={-tile.box[3]} width={tile.box[2] - tile.box[0]} height={tile.box[3] - tile.box[1]} />)}
+          </clipPath>
+        </defs>
+      ) : null}
+      {showWorld ? <BasemapPathsView paths={world ?? fallbackPaths()} palette={palette} clipPath={partial ? `url(#${clipId})` : undefined} /> : null}
+      {/* One path per tile: a tile that comes into view adds its own paths and leaves the others alone. */}
+      {level === "detail" ? ready.map((tile) => <BasemapPathsView key={tile.id} paths={loaded.get(tile.id)!} palette={palette} />) : null}
+    </g>
+  );
+}

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

@@ -0,0 +1,214 @@
+/**
+ * Land and borders under the desktop and web map: Natural Earth 1:50m for the
+ * whole world, and 1:10m tiles for the part in view once the map is zoomed in.
+ * Both are lazy chunks (see `natural-earth/`), so the app bundle carries
+ * neither. Only the desktop and web builds say where they are; the terminal,
+ * which draws its own outline, has nothing to load and bundles none of it.
+ *
+ * Paths are in degrees, x east and y south (minus the latitude), so the map
+ * places every path with one transform and pan or zoom rebuilds nothing.
+ */
+
+/** What a generated chunk exports: coordinates as integers of `STEP` degrees, polyline-encoded. */
+export interface BasemapChunk {
+  STEP: number;
+  LAND: string;
+  BORDERS: string;
+}
+
+/** West, south, east, north in degrees. */
+export type GeoBox = readonly [number, number, number, number];
+
+export interface DetailTile {
+  id: string;
+  /** What the tile was cut to: its square, a hair wider so neighbours overlap. */
+  box: GeoBox;
+  load: () => Promise<BasemapChunk>;
+}
+
+export interface BasemapPaths {
+  /** Land rings, filled even-odd so lakes stay open. */
+  land: string;
+  /** The same rings without the edges a tile, the date line or the map's southern edge cut. */
+  coast: string;
+  borders: string;
+}
+
+/** The map stops at 60°S; the 1:50m chunk is cut there. */
+const WORLD_BOX: GeoBox = [-180, -60, 180, 90];
+
+/**
+ * Pixels per degree where 1:10m takes over: a view about 30 degrees wide on
+ * a laptop. 1:50m keeps about a fiftieth of a degree, so closer in its
+ * coastlines turn into straight runs; further out 1:10m only costs paint.
+ */
+export const DETAIL_MIN_PX_PER_DEGREE = 32;
+/** Below this the world is far enough out for a faint graticule to help. */
+export const GRATICULE_MAX_PX_PER_DEGREE = 4.5;
+/** Tiles decoded and kept; a long session over many seas drops the oldest. */
+export const TILE_CACHE_SIZE = 40;
+
+export type BasemapLevel = "world" | "detail";
+
+export function basemapLevel(pxPerDegree: number): BasemapLevel {
+  return pxPerDegree >= DETAIL_MIN_PX_PER_DEGREE ? "detail" : "world";
+}
+
+/** Decodes a chunk's rings or lines into flat integer runs: x0, y0, x1, y1... */
+export function decodeParts(text: string): Int32Array[] {
+  if (!text) return [];
+  return text.split(" ").map((part) => {
+    const values: number[] = [];
+    let index = 0;
+    let lon = 0;
+    let lat = 0;
+    let axis = 0;
+    while (index < part.length) {
+      let shift = 0;
+      let bits = 0;
+      let byte = 0;
+      do {
+        byte = part.charCodeAt(index++) - 63;
+        bits |= (byte & 0x1f) << shift;
+        shift += 5;
+      } while (byte >= 0x20 && index < part.length);
+      const delta = bits & 1 ? ~(bits >> 1) : bits >> 1;
+      if (axis === 0) {
+        lon += delta;
+        values.push(lon);
+      } else {
+        lat += delta;
+        values.push(lat);
+      }
+      axis ^= 1;
+    }
+    return Int32Array.from(values);
+  });
+}
+
+function onCutEdge(x1: number, y1: number, x2: number, y2: number, box: readonly number[]): boolean {
+  return (x1 === x2 && (x1 === box[0] || x1 === box[2])) || (y1 === y2 && (y1 === box[1] || y1 === box[3]));
+}
+
+/** Builds the land, coast and border paths of one chunk cut to `box`. */
+export function basemapPaths(chunk: BasemapChunk, box: GeoBox): BasemapPaths {
+  const scale = Math.round(1 / chunk.STEP);
+  const cut = box.map((value) => Math.round(value * scale));
+  const x = (value: number) => value / scale;
+  const y = (value: number) => -value / scale;
+  let land = "";
+  let coast = "";
+  for (const ring of decodeParts(chunk.LAND)) {
+    const count = ring.length / 2;
+    if (count < 3) continue;
+    land += `M${x(ring[0]!)} ${y(ring[1]!)}`;
+    for (let index = 1; index < count; index += 1) land += `L${x(ring[index * 2]!)} ${y(ring[index * 2 + 1]!)}`;
+    land += "Z";
+    let drawing = false;
+    for (let index = 0; index < count; index += 1) {
+      const next = (index + 1) % count;
+      const x1 = ring[index * 2]!;
+      const y1 = ring[index * 2 + 1]!;
+      const x2 = ring[next * 2]!;
+      const y2 = ring[next * 2 + 1]!;
+      if (onCutEdge(x1, y1, x2, y2, cut)) {
+        drawing = false;
+        continue;
+      }
+      if (!drawing) coast += `M${x(x1)} ${y(y1)}`;
+      coast += `L${x(x2)} ${y(y2)}`;
+      drawing = true;
+    }
+  }
+  let borders = "";
+  for (const line of decodeParts(chunk.BORDERS)) {
+    for (let index = 0; index < line.length; index += 2) borders += `${index ? "L" : "M"}${x(line[index]!)} ${y(line[index + 1]!)}`;
+  }
+  return { land, coast, borders };
+}
+
+/** Tiles under the view, with a margin either side so a pan finds its tiles loaded. */
+export function tilesInView(tiles: readonly DetailTile[], view: GeoBox, margin = 0.15): DetailTile[] {
+  const padX = (view[2] - view[0]) * margin;
+  const padY = (view[3] - view[1]) * margin;
+  const west = view[0] - padX;
+  const south = view[1] - padY;
+  const east = view[2] + padX;
+  const north = view[3] + padY;
+  return tiles.filter(({ box }) => box[0] < east && box[2] > west && box[1] < north && box[3] > south);
+}
+
+/** What `natural-earth/index.chunk.ts` exports. */
+interface BasemapIndex {
+  loadWorld: () => Promise<BasemapChunk>;
+  DETAIL_TILES: readonly DetailTile[];
+}
+
+/**
+ * `./natural-earth/index.chunk.js` in the desktop and web builds, which ship
+ * the chunks beside the app; absent everywhere else. Written as the import's
+ * own specifier so a build without it has no path to follow into the data.
+ */
+declare const __GLOOM_WORLD_MAP_DATA__: string | undefined;
+
+let indexModule: Promise<BasemapIndex> | null = null;
+let worldPaths: Promise<BasemapPaths> | null = null;
+const tilePaths = new Map<string, Promise<BasemapPaths>>();
+
+function loadIndex(): Promise<BasemapIndex> {
+  if (typeof __GLOOM_WORLD_MAP_DATA__ !== "string") return Promise.reject(new Error("No map data in this build"));
+  indexModule ??= (import(__GLOOM_WORLD_MAP_DATA__) as Promise<BasemapIndex>).catch((error: unknown) => {
+    indexModule = null;
+    throw error;
+  });
+  return indexModule;
+}
+
+export function loadWorldBasemap(): Promise<BasemapPaths> {
+  worldPaths ??= loadIndex()
+    .then((index) => index.loadWorld())
+    .then((chunk) => basemapPaths(chunk, WORLD_BOX))
+    .catch((error: unknown) => {
+      worldPaths = null;
+      throw error;
+    });
+  return worldPaths;
+}
+
+export function loadDetailIndex(): Promise<readonly DetailTile[]> {
+  return loadIndex().then((index) => index.DETAIL_TILES);
+}
+
+/**
+ * Decoding a tile takes a few milliseconds; a view that needs twenty would
+ * hold a frame for a quarter of a second. They take turns, one per task.
+ */
+let decodeQueue: Promise<unknown> = Promise.resolve();
+
+function nextTask(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+export function loadDetailTile(tile: DetailTile): Promise<BasemapPaths> {
+  const cached = tilePaths.get(tile.id);
+  if (cached) {
+    // Most recently used last, so the oldest is the first to go.
+    tilePaths.delete(tile.id);
+    tilePaths.set(tile.id, cached);
+    return cached;
+  }
+  const pending = tile.load()
+    .then((chunk) => {
+      const decoded = decodeQueue.then(nextTask).then(() => basemapPaths(chunk, tile.box));
+      decodeQueue = decoded.catch(() => {});
+      return decoded;
+    })
+    .catch((error: unknown) => {
+      tilePaths.delete(tile.id);
+      throw error;
+    });
+  tilePaths.set(tile.id, pending);
+  while (tilePaths.size > TILE_CACHE_SIZE) tilePaths.delete(tilePaths.keys().next().value!);
+  return pending;
+}
+

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

@@ -0,0 +1,45 @@
+/** Map data through the Cloud client: venues, the geo layer catalog, entity pages and details. */
+import { apiClient, type CloudWorldVenueMapPayload } from "../../../api-client";
+import {
+  getGeoEntities,
+  getGeoEntity,
+  loadGeoCatalog,
+  type GeoEntitiesPayload,
+  type GeoEntitiesQuery,
+  type GeoEntityPayload,
+  type GeoLayersPayload,
+  type GeoRequest,
+} from "../../../api-client/geo";
+
+export const ENTITY_PAGE_SIZE = 100;
+
+/** Requests under /cloud/geo/ through the shared client, resolved late so tests can stub it. */
+export const cloudGeoRequest: GeoRequest = (path, init) => apiClient.geo(path, init);
+
+export async function loadWorldVenues(): Promise<CloudWorldVenueMapPayload> {
+  const response = await apiClient.getCloudWorldVenues();
+  if (!response.data) throw new Error(response.reasonCode ?? "World venue data unavailable");
+  return response.stale ? { ...response.data, stale: true } : response.data;
+}
+
+export function loadMapCatalog(request: GeoRequest = cloudGeoRequest, force = false): Promise<GeoLayersPayload | null> {
+  return loadGeoCatalog(request, { force });
+}
+
+export function loadEntityPage(
+  layerId: string,
+  query: GeoEntitiesQuery,
+  signal: AbortSignal,
+  request: GeoRequest = cloudGeoRequest,
+): Promise<GeoEntitiesPayload> {
+  return getGeoEntities(request, layerId, { limit: ENTITY_PAGE_SIZE, ...query }, signal);
+}
+
+export function loadEntityDetail(
+  layerId: string,
+  entityId: string,
+  signal?: AbortSignal,
+  request: GeoRequest = cloudGeoRequest,
+): Promise<GeoEntityPayload> {
+  return getGeoEntity(request, layerId, entityId, signal);
+}