gloomberb 0.14.0 → 0.15.0

package/src/plugins/builtin/realized-vol/pane.tsx

@@ -0,0 +1,197 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { DataTableView, EmptyState, PaneStatusBody, QueryBar, StatGrid, statGridRows, Tabs, usePaneFooter, usePaneHeaderTabs, usePaneNoticeFooter,
+  usePaneTicker, type DataTableColumn, type StatItem } from "../../../components";
+import { instrumentFromTicker, quoteSubscriptionTargetFromTicker } from "../../../market-data/request-types";
+import { useQuoteUpdates } from "../../../state/hooks/quote-streaming";
+import { useAsyncResource } from "../../../react/async-resource";
+import { useShortcut } from "../../../react/input";
+import { usePaneSettingValue, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import type { PaneProps } from "../../../types/plugin";
+import { Box, useUiCapabilities } from "../../../ui";
+import { isPlainKey } from "../../../utils/keyboard";
+import { useAutoRefresh } from "../shared/auto-refresh";
+import { useLiveStreamingSetting } from "../shared/live-streaming";
+import { useLiveSessionRefresh } from "../shared/volatility/live-session";
+import type { RealizedVolatilityEstimator, VolatilityConeStatistics } from "../shared/volatility";
+import { loadCurrentAtmIv, loadRealizedVolatilityHistory, refreshCurrentAtmIv } from "./client";
+import type { CurrentAtmIvSnapshot } from "./model";
+import { projectRealizedVolatility } from "./model";
+import { RealizedVolGraph, VolatilityConeChart } from "./charts";
+import type { RealizedVolEvidenceStatus } from "./evidence";
+import { DEFAULT_WINDOWS, ESTIMATOR_OPTIONS, selectedWindows } from "./settings";
+
+/** In session, while visible, the current ATM IV reference re-reads its expiry this often. */
+const ATM_IV_REFRESH_MS = 60_000;
+const TABS = [{ value: "graph", label: "History" }, { value: "cone", label: "Cone" }];
+const percent = (value: number | null | undefined) => value == null ? "--" : `${(value * 100).toFixed(2)}%`;
+const CONE_COLUMNS: DataTableColumn[] = [
+  { id: "window", label: "Sessions", width: 10, align: "left" },
+  ...["current", "min", "max", "mean", "median"].map((id) => ({ id, label: id[0]!.toUpperCase() + id.slice(1), width: 11, align: "right" as const })),
+  { id: "percentile", label: "Percentile", width: 12, align: "right" },
+  { id: "sampleSize", label: "Samples", width: 10, align: "right" },
+];
+
+export function RealizedVolPane({ width, height, focused }: PaneProps) {
+  const colors = useThemeColors();
+  const { nativePaneChrome } = useUiCapabilities();
+  const { symbol, ticker, financials, error: identityError } = usePaneTicker();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const [initialView] = usePaneSettingValue("initialView", "graph");
+  const [view, setView] = usePluginPaneState("activeTabId", initialView);
+  const [estimatorValue, setEstimator] = usePaneSettingValue("estimator", "close-to-close");
+  const [windowValue] = usePaneSettingValue<string[] | string>("windows", DEFAULT_WINDOWS);
+  const [lookback, setLookback] = usePaneSettingValue("lookbackYears", "1");
+  const [showIv, setShowIv] = usePaneSettingValue("showIv", true);
+  const [selected, setSelected] = usePluginPaneState("selectedWindow", 30);
+  const [sort, setSort] = useState<{ id: keyof VolatilityConeStatistics; direction: "asc" | "desc" }>({ id: "window", direction: "asc" });
+  const estimator = ESTIMATOR_OPTIONS.find((option) => option.value === estimatorValue)?.value ?? "close-to-close";
+  const windows = useMemo(() => selectedWindows(windowValue), [windowValue]);
+  const instrument = instrumentFromTicker(ticker, symbol);
+  const instrumentKey = JSON.stringify(instrument);
+  const historyController = useRef<AbortController | null>(null);
+  const ivController = useRef<AbortController | null>(null);
+  const historyLoader = useCallback(async (force: boolean) => {
+    historyController.current?.abort();
+    const controller = new AbortController();
+    historyController.current = controller;
+    const snapshot = await loadRealizedVolatilityHistory({ instrument: instrument!, forceRefresh: force, signal: controller.signal });
+    if (!snapshot.history.length && snapshot.error) throw new Error(snapshot.error);
+    return snapshot;
+  }, [instrumentKey]);
+  const quote = financials?.quote;
+  const quoteRef = useRef(quote);
+  quoteRef.current = quote;
+  const spotAvailable = !!quote && Number.isFinite(quote.price) && quote.price > 0 && !quote.stale;
+  const ivLoader = useCallback(async (force: boolean) => {
+    ivController.current?.abort();
+    const controller = new AbortController();
+    ivController.current = controller;
+    const currentQuote = quoteRef.current!;
+    return loadCurrentAtmIv({ instrument: instrument!, spot: currentQuote.price, spotAsOf: currentQuote.lastUpdated,
+      forceRefresh: force, signal: controller.signal });
+  }, [instrumentKey, spotAvailable]);
+  const history = useAsyncResource(instrument ? historyLoader : null);
+  const loadedIv = useAsyncResource(instrument && showIv && spotAvailable ? ivLoader : null);
+  useEffect(() => () => historyController.current?.abort(), [historyLoader]);
+  useEffect(() => () => ivController.current?.abort(), [ivLoader, showIv]);
+  useAutoRefresh(history.updatedAt, history.load);
+  useAutoRefresh(loadedIv.updatedAt, loadedIv.load);
+  // The pane subscribes its own quote: the IV reference is fitted at the live
+  // price even when no other pane streams this ticker. The price is only
+  // sampled at each refresh, so the slow off-screen cadence is enough.
+  const liveStreaming = useLiveStreamingSetting();
+  const quoteTarget = quoteSubscriptionTargetFromTicker(ticker, symbol, "provider");
+  useQuoteUpdates(quoteTarget ? [{ ...quoteTarget, surface: "detail", visible: false, weight: 70 }] : [], { liveStreaming });
+  // In session the reference's own expiry is re-read every minute; the full
+  // load that chose it still runs on the global refresh.
+  const [refreshedIv, setRefreshedIv] = useState<{ owner: typeof ivLoader; at: number; data: CurrentAtmIvSnapshot } | null>(null);
+  const ivDataRef = useRef<CurrentAtmIvSnapshot | null>(null);
+  const refreshIv = useCallback(async () => {
+    const previous = ivDataRef.current;
+    const currentQuote = quoteRef.current;
+    if (!previous?.reference || !instrument || !currentQuote || currentQuote.stale || !(currentQuote.price > 0)) return;
+    ivController.current?.abort();
+    const controller = new AbortController();
+    ivController.current = controller;
+    const owner = ivLoader;
+    const data = await refreshCurrentAtmIv({ instrument, spot: currentQuote.price, spotAsOf: currentQuote.lastUpdated,
+      signal: controller.signal }, previous);
+    if (!controller.signal.aborted) setRefreshedIv({ owner, at: Date.now(), data });
+  }, [ivLoader]);
+  const refreshedCurrent = refreshedIv?.owner === ivLoader && refreshedIv.at > (loadedIv.updatedAt ?? 0) ? refreshedIv.data : null;
+  const iv = { ...loadedIv, data: refreshedCurrent ?? loadedIv.data };
+  ivDataRef.current = iv.data;
+  useLiveSessionRefresh(refreshIv, ATM_IV_REFRESH_MS, showIv && spotAvailable && !!iv.data?.reference && !loadedIv.loading,
+    loadedIv.updatedAt);
+  const model = useMemo(() => history.data ? projectRealizedVolatility(history.data.history, {
+    symbol: history.data.symbol, estimator, windows, lookbackYears: Number(lookback) === 2 ? 2 : 1,
+  }) : null, [history.data, estimator, windows, lookback]);
+  const chartInput = useMemo(() => model ? { history: model.history, rolling: model.series, windows: model.windows,
+    currency: quote?.currency ?? "", iv: showIv ? iv.data?.reference ?? null : null } : null,
+  [model, quote?.currency, showIv, iv.data]);
+  const notices = [identityError, history.error, history.data?.error, iv.error, iv.data?.error,
+    ...(model?.warnings ?? []), ...(showIv ? iv.data?.warnings ?? [] : []),
+    ...(showIv && symbol && !spotAvailable ? ["Current ATM IV unavailable: underlying quote is missing or stale"] : []),
+  ].filter((value): value is string => !!value);
+  usePaneNoticeFooter({ registrationId: "realized-vol-notices", notices: [...new Set(notices)], focused });
+  const cycleView = () => setView(view === "graph" ? "cone" : "graph");
+  const openSurface = () => { if (symbol) createPaneFromTemplate("vol-surface-pane", { symbol, ticker, instrument: instrument?.instrument,
+    ...(ticker ? { listing: { name: ticker.metadata.name, exchange: ticker.metadata.exchange,
+      currency: ticker.metadata.currency, type: ticker.metadata.assetCategory ?? "STK" } } : {}),
+    values: iv.data?.reference ? { expiration: String(iv.data.reference.expiration) } : {} }); };
+  // The footer hints bind v, i and s in every view and state; only the reload
+  // is the pane's own key.
+  useShortcut((event) => {
+    if (event.defaultPrevented || !isPlainKey(event, "r")) return;
+    event.preventDefault(); event.stopPropagation();
+    void history.reload();
+    if (showIv) void iv.reload();
+  }, { enabled: focused });
+  usePaneFooter("realized-vol", () => ({ info: [
+    ...(history.loading ? [{ id: "loading", parts: [{ text: "loading history", tone: "muted" as const }] }] : []),
+    ...(history.data?.stale ? [{ id: "stale", parts: [{ text: "stale history", tone: "warning" as const }] }] : []),
+    ...(history.data ? [{ id: "cadence", parts: [{ text: "daily closes", tone: "muted" as const }] }] : []),
+    ...(model?.asOf ? [{ id: "date", parts: [{ text: model.asOf.toISOString().slice(0, 10), tone: "muted" as const }] }] : []),
+    ...(showIv && iv.loading ? [{ id: "iv-loading", parts: [{ text: "loading ATM IV", tone: "muted" as const }] }] : []),
+  ], hints: [
+    { id: "view", key: "v", label: "iew", onPress: cycleView },
+    { id: "iv", key: "i", label: showIv ? "v off" : "v on", onPress: () => setShowIv(!showIv) },
+    ...(symbol ? [{ id: "surface", key: "s", label: "urface", onPress: openSurface }] : []),
+  ] }), [history.loading, history.data, model?.asOf, iv.loading, showIv, view, symbol, iv.data]);
+  const evidence: RealizedVolEvidenceStatus = {
+    symbol: model?.symbol ?? symbol ?? "", view: view === "cone" ? "cone" : "graph", estimator,
+    windows, lookbackYears: Number(lookback) === 2 ? 2 : 1, showIv,
+    loading: history.loading || (showIv && iv.loading),
+    stale: history.data?.stale ?? false, source: history.data?.source ?? null,
+    asOf: model?.asOf?.toISOString() ?? null,
+    errors: [...new Set([history.error, history.data?.error, ...(model?.warnings ?? []),
+      ...(showIv ? [iv.error, iv.data?.error, !iv.data?.reference ? "Current ATM IV unavailable" : null] : []),
+    ].filter((value): value is string => !!value))],
+    currentIv: showIv && iv.data?.reference ? { value: iv.data.reference.value * 100,
+      date: iv.data.reference.date.toISOString(), label: iv.data.reference.label,
+      source: iv.data.reference.source, expiration: iv.data.reference.expiration } : null,
+  };
+  const tabsInHeader = usePaneHeaderTabs({ tabs: TABS, activeValue: view, onSelect: setView, focused });
+  const tabRows = tabsInHeader ? 0 : 1;
+  const reference = showIv ? iv.data?.reference ?? null : null;
+  // The cone has no IV line of its own, so the dated ATM IV it is read against sits above it.
+  const coneStats: StatItem[] = view === "cone" && model && reference
+    ? [{ id: "atm-iv", label: "ATM IV", value: percent(reference.value), detail: `${Math.round(reference.daysToExpiry)}d` }] : [];
+  const contentHeight = Math.max(4, height - 1 - tabRows - statGridRows(coneStats, width));
+  const sortedCone = [...(model?.cone ?? [])].sort((left, right) => {
+    const a = left[sort.id], b = right[sort.id];
+    return a == null ? b == null ? 0 : 1 : b == null ? -1 : (a - b) * (sort.direction === "asc" ? 1 : -1);
+  });
+  const coneTableHeight = Math.min(Math.max(2, sortedCone.length + 1), 10, Math.max(4, Math.floor(contentHeight * 0.42)));
+  return <Box width={width} height={height} flexDirection="column" overflow="hidden">
+    {!tabsInHeader && <Tabs tabs={TABS} activeValue={view} onSelect={setView} variant="underline" dense focused={focused} />}
+    <QueryBar width={width} filters={[
+      { id: "estimator", label: "Estimator", value: estimator, options: ESTIMATOR_OPTIONS, onChange: (value: string) => setEstimator(value as RealizedVolatilityEstimator) },
+      { id: "lookback", label: "Lookback", value: String(lookback), options: [{ value: "1", label: "1Y" }, { value: "2", label: "2Y" }], onChange: setLookback },
+    ]} meta={reference ? `ATM IV observed ${reference.date.toISOString().slice(0, 16).replace("T", " ")} UTC` : "Annualized %"} />
+    {!symbol ? <EmptyState title="Choose a ticker." /> : <PaneStatusBody subject="realized volatility" loading={history.loading && !model}
+      error={!model ? history.error ?? identityError ?? null : null} empty={!!model && !model.history.length}>
+      {model && view === "cone" ? <>
+        <StatGrid items={coneStats} width={width} />
+        <DataTableView<VolatilityConeStatistics> focused={focused} columns={CONE_COLUMNS} items={sortedCone}
+          rootWidth={width} rootHeight={coneTableHeight} getItemKey={(row) => String(row.window)}
+          sortColumnId={sort.id} sortDirection={sort.direction} emptyStateTitle="Volatility cone unavailable."
+          onHeaderClick={(id) => setSort({ id: id as keyof VolatilityConeStatistics, direction: sort.id === id && sort.direction === "asc" ? "desc" : "asc" })}
+          selection={{ kind: "id", selectedId: String(selected), getId: (row) => String(row.window), onChange: (_id, row) => setSelected(row.window) }}
+          onActivate={(row) => setSelected(row.window)}
+          getExportMetadata={() => [["symbol", model.symbol], ["estimator", model.estimator], ["lookback years", model.lookbackYears],
+            ["as of", model.asOf?.toISOString()], ["source", history.data?.source], ["units", "annualized %"], ["warnings", ...notices]]}
+          renderCell={(row, column) => ({ text: column.id === "window" ? String(row.window)
+            : column.id === "sampleSize" ? String(row.sampleSize)
+              : column.id === "percentile" ? row.percentile == null ? "--" : `${row.percentile.toFixed(1)}%`
+                : percent(row[column.id as "current" | "min" | "max" | "mean" | "median"]),
+            color: column.id === "current" ? colors.warning : colors.text })} />
+        {/* Desktop chrome runs a little taller than its rows; the spare row keeps the last window in view. */}
+        <VolatilityConeChart evidence={evidence} rows={model.cone} width={width}
+          height={Math.max(3, contentHeight - coneTableHeight - (nativePaneChrome ? 1 : 0))} focused={focused} />
+      </> : chartInput && windows.length ? <RealizedVolGraph evidence={evidence} input={chartInput} width={width} height={contentHeight} focused={focused} />
+        : <EmptyState title="Select graph windows in pane settings." />}
+    </PaneStatusBody>}
+  </Box>;
+}

package/src/plugins/builtin/realized-vol/settings.ts

@@ -0,0 +1,16 @@
+import { REALIZED_VOLATILITY_WINDOWS, type RealizedVolatilityEstimator } from "../shared/volatility";
+
+export const ESTIMATOR_OPTIONS: { value: RealizedVolatilityEstimator; label: string }[] = [
+  { value: "close-to-close", label: "Close to close" },
+  { value: "parkinson", label: "Parkinson" },
+  { value: "garman-klass", label: "Garman-Klass" },
+  { value: "rogers-satchell", label: "Rogers-Satchell" },
+  { value: "yang-zhang", label: "Yang-Zhang" },
+];
+export const WINDOW_OPTIONS = REALIZED_VOLATILITY_WINDOWS.map((value) => ({ value: String(value), label: `${value} sessions` }));
+export const DEFAULT_WINDOWS = ["10", "30", "90"];
+
+export function selectedWindows(value: unknown): number[] {
+  const values = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : DEFAULT_WINDOWS;
+  return [...new Set(values.map(Number).filter((window) => (REALIZED_VOLATILITY_WINDOWS as readonly number[]).includes(window)))].sort((a, b) => a - b);
+}

package/src/plugins/builtin/relative-rotation/client.ts

@@ -0,0 +1,215 @@
+import { canonicalExchange, normalizeSymbol } from "../../../utils/exchanges";
+import { apiClient } from "../../../api-client";
+import type {
+  CloudMarketResponse,
+  CloudPricePointPayload,
+  CloudQuotePayload,
+} from "../../../api-client/types";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { ApiRequestError } from "../../../api-client/errors";
+import {
+  buildRotation,
+  rotationId,
+  type RotationHistory,
+  type RotationInstrument,
+  type RotationPayload,
+} from "./model";
+
+export const rotationCache = createPluginCache<RotationPayload>({
+  kind: "relative-rotation",
+  source: "gloom-cloud",
+  schemaVersion: 2,
+  policy: { staleMs: 30 * 60_000, expireMs: 7 * 86_400_000 },
+});
+type RotationClient = Pick<
+  typeof apiClient,
+  "getCloudHistory" | "getCloudQuotesBatch"
+>;
+export function validateRotationHistory(
+  response: CloudMarketResponse<CloudPricePointPayload[]>,
+  instrument?: RotationInstrument,
+  currency?: string | null,
+): CloudPricePointPayload[] {
+  if (
+    response.status !== "success" ||
+    !Array.isArray(response.data) ||
+    !response.data.length
+  )
+    throw new Error(response.reasonCode ?? "Daily history unavailable.");
+  if (
+    response.providerMeta?.servedResolution &&
+    !["1d", "1day"].includes(response.providerMeta.servedResolution)
+  )
+    throw new Error("Cloud did not return daily bars.");
+  const metadata = response.providerMeta;
+  if (
+    instrument &&
+    ((metadata?.normalizedSymbol &&
+      normalizeSymbol(metadata.normalizedSymbol) !==
+        normalizeSymbol(instrument.symbol)) ||
+      (metadata?.normalizedExchange &&
+        instrument.exchange &&
+        canonicalExchange(metadata.normalizedExchange) !==
+          canonicalExchange(instrument.exchange)))
+  )
+    throw new Error(
+      "History listing identity does not match the requested instrument.",
+    );
+  const units = [response.currency, metadata?.currency].filter(
+    (value): value is string => !!value,
+  );
+  if (currency && units.some((value) => value !== currency))
+    throw new Error("History currency does not match the listing currency.");
+  if (
+    response.data.length > 1500 ||
+    response.data.some(
+      (row) =>
+        !row ||
+        typeof row.date !== "string" ||
+        !Number.isFinite(Date.parse(row.date)) ||
+        !Number.isFinite(row.close) ||
+        row.close <= 0,
+    )
+  )
+    throw new Error("Invalid daily history from Gloom Cloud.");
+  return response.data;
+}
+export async function fetchRotation(
+  benchmark: RotationInstrument,
+  instruments: RotationInstrument[],
+  trail = 6,
+  client: RotationClient = apiClient,
+  now = new Date(),
+): Promise<RotationPayload> {
+  const unique = [
+    ...new Map(
+      [benchmark, ...instruments].map((row) => [rotationId(row), row]),
+    ).values(),
+  ];
+  const quotes = new Map<string, CloudQuotePayload>();
+  let quoteError: string | null = null;
+  try {
+    const result = await client.getCloudQuotesBatch(unique, "cache-first");
+    for (const item of result.data?.items ?? []) {
+      const instrument = unique.find(
+        (row) =>
+          row.symbol === item.symbol &&
+          (canonicalExchange(row.exchange) ===
+            canonicalExchange(item.exchange) ||
+            !row.exchange),
+      );
+      if (instrument && item.status === "success" && item.data)
+        quotes.set(rotationId(instrument), item.data);
+    }
+  } catch (error) {
+    if (
+      error instanceof ApiRequestError &&
+      [401, 403].includes(error.status ?? 0)
+    )
+      throw error;
+    quoteError = "Listing currencies unavailable.";
+  }
+  const start = new Date(now);
+  start.setUTCFullYear(start.getUTCFullYear() - 3);
+  start.setUTCDate(1);
+  const end = now.toISOString().slice(0, 10),
+    startDate = start.toISOString().slice(0, 10);
+  const results = new Map<string, RotationHistory>();
+  let next = 0;
+  // Bound Cloud history requests; shared server caches batch upstream demand.
+  await Promise.all(
+    Array.from({ length: Math.min(4, unique.length) }, async () => {
+      while (next < unique.length) {
+        const instrument = unique[next++]!,
+          id = rotationId(instrument),
+          currency = quotes.get(id)?.currency ?? null;
+        try {
+          const response = await client.getCloudHistory(
+            instrument.symbol,
+            instrument.exchange,
+            {
+              interval: "1day",
+              outputsize: 1000,
+              startDate,
+              endDate: end,
+              rangeKey: "3Y",
+            },
+          );
+          results.set(id, {
+            instrument,
+            currency,
+            points: validateRotationHistory(response, instrument, currency),
+            asOf: response.asOf ?? null,
+            stale: response.stale === true,
+            error: quoteError,
+          });
+        } catch (error) {
+          if (
+            error instanceof ApiRequestError &&
+            [401, 403].includes(error.status ?? 0)
+          )
+            throw error;
+          results.set(id, {
+            instrument,
+            currency,
+            points: [],
+            asOf: null,
+            stale: false,
+            error:
+              error instanceof Error ? error.message : "History unavailable.",
+          });
+        }
+      }
+    }),
+  );
+  return buildRotation(
+    results.get(rotationId(benchmark))!,
+    instruments.map((row) => results.get(rotationId(row))!),
+    trail,
+    now,
+  );
+}
+const key = (
+  benchmark: RotationInstrument,
+  instruments: RotationInstrument[],
+  trail: number,
+) =>
+  `${rotationId(benchmark)}|${instruments.map(rotationId).join(",")}|${trail}`;
+export function cachedRotation(
+  benchmark: RotationInstrument,
+  instruments: RotationInstrument[],
+  trail: number,
+) {
+  const value = rotationCache.get(key(benchmark, instruments, trail), {
+    allowExpired: true,
+  });
+  return value
+    ? {
+        payload: value.data,
+        stale: value.stale,
+        refreshError: null as string | null,
+      }
+    : null;
+}
+export async function loadRotation(
+  benchmark: RotationInstrument,
+  instruments: RotationInstrument[],
+  trail: number,
+  force = false,
+) {
+  const result = await rotationCache.load(
+    key(benchmark, instruments, trail),
+    () => fetchRotation(benchmark, instruments, trail),
+    { force },
+  );
+  if (
+    result.error instanceof ApiRequestError &&
+    [401, 403].includes(result.error.status ?? 0)
+  )
+    throw result.error;
+  return {
+    payload: result.data,
+    stale: result.stale,
+    refreshError: result.refreshError ?? null,
+  };
+}

package/src/plugins/builtin/relative-rotation/headless.ts

@@ -0,0 +1,93 @@
+import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import { fetchRotation } from "./client";
+import { rotationInstruments, sectorRotationInstruments } from "./model";
+
+/** Same rounding as the pane: ratios to 2 decimals, percentiles whole. */
+const fixed = (value: unknown, digits: number) =>
+  typeof value === "number" && Number.isFinite(value) ? value.toFixed(digits) : "--";
+
+export const rotationHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  argument: {
+    kind: "symbol-list",
+    optional: true,
+    maximum: 24,
+    description: "Symbols or SYMBOL:EXCHANGE; defaults to US sectors.",
+  },
+  options: [
+    {
+      key: "benchmark",
+      type: "string",
+      description: "Benchmark listing.",
+      defaultValue: "SPY:NYSEARCA",
+    },
+    {
+      key: "trail",
+      type: "integer",
+      description: "Completed weeks in each trail.",
+      defaultValue: 6,
+      minimum: 2,
+      maximum: 12,
+    },
+  ],
+  describe: "Relative rotation",
+  discovery: {
+    aliases: ["RRG", "GRR"],
+    dataRequirements: ["Cloud daily history and listing currencies"],
+    limitations: [
+      "Transparent 13-week strength and 4-week momentum, not proprietary JdK indices",
+      "Same-currency price returns; dividends are not reinvested",
+      "Completed weeks only",
+    ],
+  },
+  async load(args, ctx) {
+    const references = rotationInstruments(
+      String(args.options.benchmark ?? "SPY:NYSEARCA"),
+    );
+    if (references.length !== 1) throw new Error("Choose one benchmark.");
+    const instruments = args.symbols.length
+      ? rotationInstruments(args.symbols.join(","))
+      : sectorRotationInstruments();
+    const data = await fetchRotation(
+      references[0]!,
+      instruments,
+      Number(args.options.trail ?? 6),
+      ctx.apiClient,
+    );
+    const errors = [
+      ...data.gaps,
+      ...data.rows.flatMap((row) =>
+        row.gaps.map((gap) => `${row.symbol}: ${gap}`),
+      ),
+    ];
+    return {
+      complete: errors.length === 0,
+      symbols: instruments.map((row) => row.symbol),
+      unavailableSymbols: data.rows
+        .filter((row) => row.strength == null)
+        .map((row) => row.symbol),
+      errors,
+      sections: [
+        {
+          title: `Versus ${data.benchmark.symbol}`,
+          columns: [
+            { key: "symbol", header: "Symbol" },
+            { key: "label", header: "Name" },
+            { key: "quadrant", header: "Quadrant" },
+            { key: "strength", header: "Strength", align: "right", format: (value) => fixed(value, 2) },
+            { key: "strengthPercentile", header: "Pctl 1Y", align: "right", format: (value) => fixed(value, 0) },
+            { key: "momentum", header: "Momentum", align: "right", format: (value) => fixed(value, 2) },
+            { key: "momentumPercentile", header: "Pctl 1Y", align: "right", format: (value) => fixed(value, 0) },
+            { key: "asOf", header: "As of" },
+          ],
+          rows: data.rows.map((row) => ({
+            ...row,
+            strengthPercentile: row.strengthRank.percentile,
+            momentumPercentile: row.momentumRank.percentile,
+          })),
+        },
+      ],
+      metadata: { ...data },
+    };
+  },
+};

package/src/plugins/builtin/relative-rotation/index.tsx

@@ -0,0 +1,88 @@
+import type { PluginModule } from "../plugin-module";
+import { rotationCache } from "./client";
+import { rotationHeadless } from "./headless";
+import { RelativeRotationPane } from "./pane";
+
+export const relativeRotationModule: PluginModule = {
+  panes: [
+    {
+      id: "relative-rotation",
+      name: "Relative Rotation",
+      icon: "R",
+      component: RelativeRotationPane,
+      defaultPosition: "right",
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 100, height: 36 },
+      tableExport: true,
+      headless: rotationHeadless,
+      settings: {
+        title: "Relative Rotation",
+        fields: [
+          {
+            key: "scope",
+            label: "Universe",
+            type: "select",
+            options: [
+              { value: "sectors", label: "US sectors" },
+              { value: "collection", label: "Linked watchlist or portfolio" },
+              { value: "custom", label: "Custom symbols" },
+            ],
+          },
+          {
+            key: "symbols",
+            label: "Custom symbols",
+            type: "text",
+            placeholder: "AAPL:NASDAQ, MSFT:NASDAQ",
+          },
+          {
+            key: "benchmark",
+            label: "Benchmark",
+            type: "text",
+            placeholder: "SPY:NYSEARCA",
+          },
+          {
+            key: "trail",
+            label: "Trail weeks",
+            type: "select",
+            options: Array.from({ length: 11 }, (_, index) => index + 2).map(
+              (value) => ({
+                value: String(value),
+                label: String(value),
+              }),
+            ),
+          },
+        ],
+      },
+    },
+  ],
+  paneTemplates: [{
+    id: "relative-rotation-rrg",
+    paneId: "relative-rotation",
+    label: "Relative Rotation",
+    description:
+      "Sector or watchlist strength and momentum versus a benchmark, with weekly trails.",
+    keywords: [
+      "relative",
+      "rotation",
+      "strength",
+      "momentum",
+      "sector",
+      "rrg",
+      "grr",
+    ],
+    shortcut: { prefix: "RRG", aliases: ["GRR"], argKind: "ticker-list" as const, argOptional: true },
+    headless: rotationHeadless,
+    createInstance: (_context, options) => ({
+      settings: options?.symbols?.length
+        ? { scope: "custom", symbols: options.symbols.join(",") }
+        : { scope: "sectors" },
+      placement: "floating" as const,
+    }),
+  }],
+  setup(ctx) {
+    rotationCache.attach(ctx.persistence);
+  },
+  dispose() {
+    rotationCache.reset();
+  },
+};