gloomberb 0.11.3 → 0.12.0

package/src/plugins/builtin/news/wire/breaking/notifications.test.ts

@@ -1,12 +1,20 @@
 import { describe, expect, test } from "bun:test";
 import type { AppNotificationRequest, GloomPluginContext } from "../../../../../types/plugin";
 import type { MarketNewsItem, NewsQueryState } from "../../../../../types/news-source";
+import {
+  BREAKING_NEWS_MUTED_SECTORS_KEY,
+  BREAKING_NEWS_SCOPE_KEY,
+} from "./filters";
 import {
   BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY,
   setupBreakingNewsNotifications,
 } from "./notifications";
 
-function article(id: string, title = id): MarketNewsItem {
+function article(
+  id: string,
+  title = id,
+  overrides: Partial<MarketNewsItem> = {},
+): MarketNewsItem {
   return {
     id,
     title,
@@ -18,16 +26,11 @@ function article(id: string, title = id): MarketNewsItem {
     sectors: [],
     categories: ["general"],
     tickers: ["AAPL"],
-    scores: {
-      importance: 90,
-      urgency: 90,
-      marketImpact: 80,
-      novelty: 80,
-      confidence: 90,
-    },
+    scores: { importance: 90, urgency: 90, marketImpact: 80, novelty: 80, confidence: 90 },
     importance: 90,
     isBreaking: true,
     isDeveloping: false,
+    ...overrides,
   };
 }
 
@@ -43,58 +46,159 @@ function ready(articles: MarketNewsItem[]): NewsQueryState {
   };
 }
 
+interface Harness {
+  ctx: GloomPluginContext;
+  notifications: AppNotificationRequest[];
+  shownPanes: string[];
+  state: Map<string, unknown>;
+  emit(articles: MarketNewsItem[]): void;
+  isWatching(): boolean;
+}
+
+function harness(options: {
+  settings?: Record<string, unknown>;
+  watchedSymbols?: string[];
+} = {}): Harness {
+  let listener: ((state: NewsQueryState) => void) | null = null;
+  const notifications: AppNotificationRequest[] = [];
+  const shownPanes: string[] = [];
+  const state = new Map<string, unknown>();
+  const settings: Record<string, unknown> = {
+    [BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY]: true,
+    ...options.settings,
+  };
+  const watched = options.watchedSymbols ?? ["AAPL"];
+
+  const ctx = {
+    configState: { get: (key: string) => settings[key] ?? null },
+    persistence: {
+      getState: (key: string) => state.get(key) ?? null,
+      setState: (key: string, value: unknown) => void state.set(key, value),
+    },
+    tickerRepository: {
+      loadAllTickers: async () =>
+        watched.map((symbol) => ({
+          metadata: { ticker: symbol, watchlists: ["default"], portfolios: [], positions: [] },
+        })),
+    },
+    watchNewsQuery: (_query: unknown, next: (state: NewsQueryState) => void) => {
+      listener = next;
+      return () => {
+        listener = null;
+      };
+    },
+    on: () => () => {},
+    notify: (notification: AppNotificationRequest) => void notifications.push(notification),
+    showPane: (paneId: string) => void shownPanes.push(paneId),
+    log: { warn: () => {} },
+  } as unknown as GloomPluginContext;
+
+  return {
+    ctx,
+    notifications,
+    shownPanes,
+    state,
+    emit: (articles) => listener?.(ready(articles)),
+    isWatching: () => listener !== null,
+  };
+}
+
+/** Lets the async watchlist load settle before articles arrive. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
 describe("breaking news notifications", () => {
-  test("primes on the first ready batch and notifies for later unseen articles", () => {
-    let enabled = true;
-    let listener: ((state: NewsQueryState) => void) | null = null;
-    const notifications: AppNotificationRequest[] = [];
-    const shownPanes: string[] = [];
-
-    const ctx = {
-      configState: {
-        get: (key: string) => key === BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY ? enabled : null,
-      },
-      watchNewsQuery: (_query: unknown, nextListener: (state: NewsQueryState) => void) => {
-        listener = nextListener;
-        return () => {
-          listener = null;
-        };
-      },
-      on: (_event: string, _handler: unknown) => () => {},
-      notify: (notification: AppNotificationRequest) => {
-        notifications.push(notification);
-      },
-      showPane: (paneId: string) => {
-        shownPanes.push(paneId);
-      },
-      log: {
-        warn: () => {},
-      },
-    } as unknown as GloomPluginContext;
-
-    const dispose = setupBreakingNewsNotifications(ctx);
-    const oldArticle = article("old", "Old headline");
-    const newArticle = article("new", "New headline");
-
-    listener?.(ready([oldArticle]));
-    listener?.(ready([newArticle, oldArticle]));
-
-    expect(notifications).toHaveLength(1);
-    expect(notifications[0]).toMatchObject({
+  test("primes on the first ready batch and notifies for later unseen articles", async () => {
+    const h = harness();
+    const dispose = setupBreakingNewsNotifications(h.ctx);
+    await settle();
+
+    const old = article("old", "Old headline");
+    const fresh = article("new", "New headline");
+
+    h.emit([old]);
+    h.emit([fresh, old]);
+
+    expect(h.notifications).toHaveLength(1);
+    expect(h.notifications[0]).toMatchObject({
       title: "Breaking News",
       body: "New headline",
       desktop: "always",
-      persistent: true,
     });
+    // Breaking toasts must expire on their own; persistent ones stacked up.
+    expect(h.notifications[0]?.persistent).toBeUndefined();
+    expect(h.notifications[0]?.duration).toBeGreaterThan(0);
 
-    notifications[0]!.action?.onClick();
-    expect(shownPanes).toEqual(["news-breaking"]);
-
-    enabled = false;
-    listener?.(ready([article("newer", "Newer headline"), newArticle, oldArticle]));
-    expect(notifications).toHaveLength(1);
+    h.notifications[0]!.action?.onClick();
+    expect(h.shownPanes).toEqual(["news-breaking"]);
 
     dispose();
-    expect(listener).toBeNull();
+    expect(h.isWatching()).toBe(false);
+  });
+
+  test("default scope drops stories about tickers the user does not track", async () => {
+    const h = harness({ watchedSymbols: ["AAPL"] });
+    setupBreakingNewsNotifications(h.ctx);
+    await settle();
+
+    h.emit([article("seed")]);
+    h.emit([
+      article("unrelated", "Unrelated ticker", { tickers: ["XOM"] }),
+      article("seed"),
+    ]);
+    expect(h.notifications).toHaveLength(0);
+
+    h.emit([article("macro", "Market-wide event", { tickers: [] }), article("seed")]);
+    expect(h.notifications).toHaveLength(1);
+    expect(h.notifications[0]?.body).toBe("Market-wide event");
+  });
+
+  test("muted sectors suppress otherwise in-scope stories", async () => {
+    const h = harness({
+      settings: { [BREAKING_NEWS_MUTED_SECTORS_KEY]: ["health_care"] },
+    });
+    setupBreakingNewsNotifications(h.ctx);
+    await settle();
+
+    h.emit([article("seed")]);
+    h.emit([
+      article("pharma", "Pharma story", { sectors: ["health_care"] }),
+      article("seed"),
+    ]);
+    expect(h.notifications).toHaveLength(0);
+  });
+
+  test("filtered-out articles are still marked seen so relaxing a filter replays nothing", async () => {
+    const h = harness({ settings: { [BREAKING_NEWS_SCOPE_KEY]: "watchlist" } });
+    setupBreakingNewsNotifications(h.ctx);
+    await settle();
+
+    h.emit([article("seed")]);
+    const macro = article("macro", "Market-wide event", { tickers: [] });
+    h.emit([macro, article("seed")]);
+    expect(h.notifications).toHaveLength(0);
+
+    // Same article arriving again must not notify once it has been observed.
+    h.emit([macro, article("seed")]);
+    expect(h.notifications).toHaveLength(0);
+  });
+
+  test("snoozing suppresses notifications until the window passes", async () => {
+    const h = harness();
+    setupBreakingNewsNotifications(h.ctx);
+    await settle();
+
+    h.emit([article("seed")]);
+    h.emit([article("first", "First"), article("seed")]);
+    expect(h.notifications).toHaveLength(1);
+
+    h.notifications[0]!.secondaryAction?.onClick();
+    const confirmation = h.notifications.length;
+
+    h.emit([article("second", "Second"), article("seed")]);
+    expect(h.notifications).toHaveLength(confirmation);
+
+    h.state.set("breaking-news-snooze-until", Date.now() - 1);
+    h.emit([article("third", "Third"), article("seed")]);
+    expect(h.notifications.at(-1)?.body).toBe("Third");
   });
 });

package/src/plugins/builtin/news/wire/breaking/notifications.ts

@@ -1,10 +1,22 @@
 import type { GloomPluginContext } from "../../../../../types/plugin";
 import type { MarketNewsItem, NewsQueryState } from "../../../../../types/news-source";
 import { NEWS_QUERY_PRESETS } from "../news/query-presets";
+import {
+  BREAKING_NEWS_MUTED_SECTORS_KEY,
+  BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY,
+  BREAKING_NEWS_SCOPE_KEY,
+  parseBreakingScope,
+  parseMutedSectors,
+  selectNotifiableArticles,
+} from "./filters";
 
-export const BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY = "breakingNewsNotificationsEnabled";
+export { BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY };
 
 const MAX_SEEN_ARTICLE_IDS = 500;
+/** Long enough to read a stacked burst, short enough to clear itself. */
+const BREAKING_TOAST_DURATION_MS = 20_000;
+const SNOOZE_DURATION_MS = 60 * 60_000;
+const SNOOZE_STATE_KEY = "breaking-news-snooze-until";
 
 function isReadyState(state: NewsQueryState): boolean {
   return state.phase === "ready" || state.phase === "refreshing";
@@ -35,32 +47,70 @@ function notificationSubtitle(article: MarketNewsItem): string {
   return tickers ? `${article.source} ${tickers}` : article.source;
 }
 
-function notifyNewBreakingArticles(ctx: GloomPluginContext, articles: MarketNewsItem[]): void {
-  const latest = [...articles].sort((a, b) => b.publishedAt.getTime() - a.publishedAt.getTime())[0];
-  if (!latest) return;
-
-  const extraCount = articles.length - 1;
-  ctx.notify({
-    title: "Breaking News",
-    subtitle: notificationSubtitle(latest),
-    body: extraCount > 0 ? `${latest.title} (+${extraCount} more)` : latest.title,
-    type: "info",
-    desktop: "always",
-    persistent: true,
-    action: {
-      label: "Open",
-      onClick: () => ctx.showPane("news-breaking"),
-    },
-  });
-}
-
 export function setupBreakingNewsNotifications(ctx: GloomPluginContext): () => void {
   let disposeWatch: (() => void) | null = null;
   let primed = false;
   let seenArticleIds = new Set<string>();
+  let watchedSymbols = new Set<string>();
 
   const enabled = () => ctx.configState.get<boolean>(BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY) === true;
 
+  // Snooze is intentionally local: it is short-lived and must not race the
+  // cloud sync snapshot across devices.
+  const snoozedUntil = () => ctx.persistence.getState<number>(SNOOZE_STATE_KEY) ?? 0;
+  const isSnoozed = () => snoozedUntil() > Date.now();
+  const snooze = () => {
+    ctx.persistence.setState(SNOOZE_STATE_KEY, Date.now() + SNOOZE_DURATION_MS);
+    ctx.notify({
+      body: "Breaking news snoozed for 1 hour.",
+      type: "info",
+      desktop: "never",
+    });
+  };
+
+  const refreshWatchedSymbols = async () => {
+    try {
+      const tickers = await ctx.tickerRepository.loadAllTickers();
+      const next = new Set<string>();
+      for (const ticker of tickers) {
+        const metadata = ticker.metadata;
+        const tracked =
+          (metadata.watchlists?.length ?? 0) > 0 ||
+          (metadata.portfolios?.length ?? 0) > 0 ||
+          (metadata.positions?.length ?? 0) > 0;
+        if (tracked) next.add(metadata.ticker.toUpperCase());
+      }
+      watchedSymbols = next;
+    } catch (error) {
+      ctx.log.warn(`breaking notifications could not load watched tickers: ${error}`);
+    }
+  };
+
+  const notifyNewBreakingArticles = (articles: MarketNewsItem[]): void => {
+    const latest = [...articles].sort(
+      (a, b) => b.publishedAt.getTime() - a.publishedAt.getTime(),
+    )[0];
+    if (!latest) return;
+
+    const extraCount = articles.length - 1;
+    ctx.notify({
+      title: "Breaking News",
+      subtitle: notificationSubtitle(latest),
+      body: extraCount > 0 ? `${latest.title} (+${extraCount} more)` : latest.title,
+      type: "info",
+      desktop: "always",
+      duration: BREAKING_TOAST_DURATION_MS,
+      action: {
+        label: "Open",
+        onClick: () => ctx.showPane("news-breaking"),
+      },
+      secondaryAction: {
+        label: "Snooze 1h",
+        onClick: snooze,
+      },
+    });
+  };
+
   const handleState = (state: NewsQueryState) => {
     if (!isReadyState(state)) return;
 
@@ -71,12 +121,20 @@ export function setupBreakingNewsNotifications(ctx: GloomPluginContext): () => v
     }
 
     const freshArticles = state.articles.filter((article) => !seenArticleIds.has(article.id));
+    // Mark everything seen regardless of filtering, so relaxing a filter later
+    // does not replay a backlog of old stories as if they just broke.
+    seenArticleIds = rememberArticleIds(seenArticleIds, state.articles);
     if (freshArticles.length === 0) return;
+    if (!enabled() || isSnoozed()) return;
 
-    seenArticleIds = rememberArticleIds(seenArticleIds, state.articles);
-    if (enabled()) {
-      notifyNewBreakingArticles(ctx, freshArticles);
-    }
+    const notifiable = selectNotifiableArticles(freshArticles, {
+      scope: parseBreakingScope(ctx.configState.get(BREAKING_NEWS_SCOPE_KEY)),
+      mutedSectors: parseMutedSectors(ctx.configState.get(BREAKING_NEWS_MUTED_SECTORS_KEY)),
+      watchedSymbols,
+    });
+    if (notifiable.length === 0) return;
+
+    notifyNewBreakingArticles(notifiable);
   };
 
   const stop = () => {
@@ -92,6 +150,7 @@ export function setupBreakingNewsNotifications(ctx: GloomPluginContext): () => v
       ctx.log.warn("breaking notifications unavailable: news query watcher missing");
       return;
     }
+    void refreshWatchedSymbols();
     disposeWatch = ctx.watchNewsQuery(NEWS_QUERY_PRESETS.breaking, handleState);
   };
 
@@ -100,11 +159,18 @@ export function setupBreakingNewsNotifications(ctx: GloomPluginContext): () => v
     else stop();
   };
 
-  const disposeConfigListener = ctx.on("config:changed", sync);
+  const disposeConfigListener = ctx.on("config:changed", () => {
+    void refreshWatchedSymbols();
+    sync();
+  });
+  const disposeTickerAdded = ctx.on("ticker:added", () => void refreshWatchedSymbols());
+  const disposeTickerRemoved = ctx.on("ticker:removed", () => void refreshWatchedSymbols());
   sync();
 
   return () => {
     disposeConfigListener();
+    disposeTickerAdded();
+    disposeTickerRemoved();
     stop();
   };
 }

package/src/plugins/builtin/news/wire/index.tsx

@@ -6,6 +6,12 @@ import {
   BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY,
   setupBreakingNewsNotifications,
 } from "./breaking/notifications";
+import {
+  BREAKING_MUTED_SECTOR_OPTIONS,
+  BREAKING_NEWS_MUTED_SECTORS_KEY,
+  BREAKING_NEWS_SCOPE_KEY,
+  BREAKING_SCOPE_OPTIONS,
+} from "./breaking/filters";
 import {
   addUserNewsFeed,
   getEnabledNewsFeeds,
@@ -17,12 +23,6 @@ import { NewsPresetPane } from "./news/preset-pane";
 import { NEWS_QUERY_PRESETS } from "./news/query-presets";
 import type { NewsColumnId, NewsSortPreference } from "./news/table";
 import { createRssNewsCapability } from "./rss/source";
-import { openUrl } from "../../../../components/ui/external-link";
-import {
-  cachedNewsArticles,
-  loadNewsArticles,
-  searchNewsArticles,
-} from "./article-search";
 
 interface NewsPresetPaneConfig {
   paneKey: string;
@@ -77,13 +77,31 @@ export const newsWireModule: PluginModule = {
       defaultFloatingSize: { width: 85, height: 20 },
       settings: {
         title: "Breaking News Settings",
-        fields: [{
-          key: BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY,
-          label: "Notifications",
-          description: "Notify when new breaking stories arrive, even while this pane is closed.",
-          type: "toggle",
-          storage: "plugin",
-        }],
+        fields: [
+          {
+            key: BREAKING_NEWS_NOTIFICATIONS_ENABLED_KEY,
+            label: "Notifications",
+            description: "Notify when new breaking stories arrive, even while this pane is closed.",
+            type: "toggle",
+            storage: "plugin",
+          },
+          {
+            key: BREAKING_NEWS_SCOPE_KEY,
+            label: "Notify About",
+            description: "Which breaking stories are worth interrupting you for.",
+            type: "select",
+            storage: "plugin",
+            options: BREAKING_SCOPE_OPTIONS,
+          },
+          {
+            key: BREAKING_NEWS_MUTED_SECTORS_KEY,
+            label: "Muted Sectors",
+            description: "Never notify about stories confined to these sectors.",
+            type: "multi-select",
+            storage: "plugin",
+            options: BREAKING_MUTED_SECTOR_OPTIONS,
+          },
+        ],
       },
     },
   ],
@@ -105,37 +123,6 @@ export const newsWireModule: PluginModule = {
     );
     ctx.registerCapability(source);
 
-    ctx.registerCommand({
-      id: "open-news-article",
-      label: "Open Article",
-      description: "Search loaded news headlines by topic, e.g. ART hormuz.",
-      keywords: ["article", "news", "rss", "headline", "story", "open"],
-      category: "navigation",
-      shortcut: "ART",
-      shortcutArg: {
-        placeholder: "headline or topic",
-        kind: "text",
-        parse: (arg) => ({ query: arg.trim() }),
-      },
-      async execute(values) {
-        const query = values?.query ?? values?.shortcut ?? "";
-        const articles = cachedNewsArticles().length > 0
-          ? cachedNewsArticles()
-          : await loadNewsArticles();
-        const match = searchNewsArticles(articles, query)[0];
-        if (!match) {
-          ctx.notify({
-            body: query.trim()
-              ? `No article matched "${query.trim()}".`
-              : "No articles loaded yet.",
-            type: "error",
-          });
-          return;
-        }
-        openUrl(match.url);
-      },
-    });
-
     ctx.registerCommand({
       id: "add-news-feed",
       label: "Add News Feed",

package/src/plugins/builtin/options/index.tsx

@@ -54,6 +54,7 @@ export const optionsModule: PluginModule = {
       defaultFloatingSize: { width: 112, height: 28 },
       quickSettings: [LIVE_STREAMING_QUICK_SETTING],
       settings: (context) => withLiveStreamingSetting(optionsSettings(context.settings), context.settings),
+      tableExport: true,
     },
   ],
 

package/src/plugins/builtin/options/view.test.tsx

@@ -1,7 +1,8 @@
 import { afterEach, expect, test } from "bun:test";
 import { act, useState } from "react";
 import type { ScrollBoxRenderable } from "@opentui/core";
-import { testRender } from "../../../renderers/opentui/test-utils";
+import { takeSavedTextFile, testRender } from "../../../renderers/opentui/test-utils";
+import { exportPaneTable, hasPaneTableExporter } from "../../../state/pane-table-export-registry";
 import { MarketDataCoordinator, setSharedMarketDataCoordinator } from "../../../market-data/coordinator";
 import { AppContext, PaneInstanceProvider, createInitialState } from "../../../state/app/context";
 import { createTestDataProvider } from "../../../test-support/data-provider";
@@ -152,6 +153,33 @@ afterEach(async () => {
   setSharedMarketDataCoordinator(null);
 });
 
+test("exposes exactly one exportable table so CSV export stays wired up", async () => {
+  const provider = createTestDataProvider({
+    getOptionsChain: async () => makeChain([100, 101], 101),
+  });
+  setSharedMarketDataCoordinator(new MarketDataCoordinator(provider));
+
+  await act(async () => {
+    testSetup = await testRender(
+      <OptionsHarness ticker={makeTicker("AAPL")} quotePrice={101} />,
+      { width: 124, height: 12 },
+    );
+  });
+  await renderSettled();
+
+  // `tableExport: true` on the options pane only works when the pane mounts a single
+  // DataTable; a second concurrent table would silently disable the export action.
+  expect(hasPaneTableExporter(TEST_PANE_ID)).toBe(true);
+
+  const location = await exportPaneTable(TEST_PANE_ID, "options.csv");
+  expect(location).toBe("~/Downloads/options.csv");
+
+  const saved = takeSavedTextFile();
+  expect(saved?.name).toBe("options.csv");
+  expect(saved?.text.split("\n")[0]).toContain("STRIKE");
+  expect(saved?.text).toContain("101");
+});
+
 test("defaults the table around the nearest strike to the current quote", async () => {
   const strikes = Array.from({ length: 25 }, (_, index) => 50 + index * 5);
   const provider = createTestDataProvider({

package/src/plugins/builtin/options/view.tsx

@@ -423,25 +423,6 @@ export function OptionsView({ width, height, focused, onCapture = () => {} }: Op
       return true;
     }
 
-    if (isPlainKey(event, "j", "down")) {
-      if (strikes.length === 0) return true;
-      event.preventDefault?.();
-      event.stopPropagation?.();
-      userSelectedStrikeRef.current = true;
-      setScrollToIndexAlign("nearest");
-      setStrikeIdx((i) => Math.min(i + 1, strikes.length - 1));
-      return true;
-    }
-    if (isPlainKey(event, "k", "up")) {
-      if (strikes.length === 0) return true;
-      event.preventDefault?.();
-      event.stopPropagation?.();
-      userSelectedStrikeRef.current = true;
-      setScrollToIndexAlign("nearest");
-      setStrikeIdx((i) => Math.max(i - 1, 0));
-      return true;
-    }
-
     return false;
   }, [
     calcParams,
@@ -450,7 +431,6 @@ export function OptionsView({ width, height, focused, onCapture = () => {} }: Op
     interactive,
     openCalculator,
     selectAdjacentExpiration,
-    strikes.length,
   ]);
 
   if (!ticker) {
@@ -522,11 +502,10 @@ export function OptionsView({ width, height, focused, onCapture = () => {} }: Op
             setStrikeIdx(index);
           },
         }}
-        onCursorChange={(_row, index) => {
+        onCursorChange={() => {
           userSelectedStrikeRef.current = true;
           setScrollToIndexAlign("nearest");
           enterInteractive();
-          setStrikeIdx(index);
         }}
         onRootKeyDown={handleTableKeyDown}
         headerScrollId="options-table-header-scroll"

package/src/plugins/builtin/plugin-marketplace/feed.ts

@@ -0,0 +1,80 @@
+import { createThrottledFetch } from "../../../utils/throttled-fetch";
+import type { RegistryFeed, RegistryPlugin } from "./model";
+
+/**
+ * Exported so the hosted build's CSP can be checked against it. The browser
+ * renderer can only reach origins listed in `connect-src`, and a blocked fetch
+ * shows up as an empty catalog rather than an error, so the two are pinned
+ * together by a test.
+ */
+export const REGISTRY_ORIGIN = "https://plugins.gloom.sh";
+const REGISTRY_URL = `${REGISTRY_ORIGIN}/registry.json`;
+const FRESH_MS = 15 * 60_000;
+
+const registryFetch = createThrottledFetch({
+  requestsPerMinute: 20,
+  maxRetries: 2,
+  timeoutMs: 10_000,
+  backoffBaseMs: 500,
+  dedupeGetRequests: true,
+  defaultHeaders: { Accept: "application/json" },
+});
+
+interface CacheEntry {
+  plugins: RegistryPlugin[];
+  fetchedAt: number;
+}
+
+let cache: CacheEntry | null = null;
+let inFlight: Promise<RegistryPlugin[]> | null = null;
+
+export interface FeedResult {
+  plugins: RegistryPlugin[];
+  fetchedAt: number | null;
+  /** Served from cache after a failed refresh. */
+  stale: boolean;
+  error: string | null;
+}
+
+function parseFeed(body: unknown): RegistryPlugin[] {
+  const feed = body as RegistryFeed | null;
+  if (!feed || !Array.isArray(feed.plugins)) throw new Error("Malformed registry feed");
+  // Only fields the pane actually reads are required; the rest degrade to defaults
+  // so a feed built by a newer registry version still renders.
+  return feed.plugins.filter((plugin): plugin is RegistryPlugin => (
+    !!plugin && typeof plugin.id === "string" && typeof plugin.name === "string"
+  ));
+}
+
+export async function loadRegistry(options: { force?: boolean } = {}): Promise<FeedResult> {
+  const now = Date.now();
+  if (!options.force && cache && now - cache.fetchedAt < FRESH_MS) {
+    return { plugins: cache.plugins, fetchedAt: cache.fetchedAt, stale: false, error: null };
+  }
+
+  if (!inFlight) {
+    inFlight = (async () => {
+      const response = await registryFetch.fetch(REGISTRY_URL);
+      if (!response.ok) throw new Error(`Registry request failed (${response.status})`);
+      return parseFeed(await response.json());
+    })().finally(() => {
+      inFlight = null;
+    });
+  }
+
+  try {
+    const plugins = await inFlight;
+    cache = { plugins, fetchedAt: Date.now() };
+    return { plugins, fetchedAt: cache.fetchedAt, stale: false, error: null };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // A stale catalog is far more useful than an empty pane, and the footer
+    // says which one the user is looking at.
+    if (cache) return { plugins: cache.plugins, fetchedAt: cache.fetchedAt, stale: true, error: message };
+    return { plugins: [], fetchedAt: null, stale: false, error: message };
+  }
+}
+
+export function registryPluginUrl(id: string): string {
+  return `https://gloom.sh/plugins/${id}`;
+}