gloomberb 0.10.4 → 0.11.0

package/src/plugins/builtin/market-movers/screener.ts

@@ -1,5 +1,13 @@
 import { createThrottledFetch, type ThrottledFetchTransport } from "../../../utils/throttled-fetch";
 import type { PluginPersistence } from "../../../types/plugin";
+import { apiClient } from "../../../api-client";
+import type {
+  CloudMarketResponse,
+  CloudMarketScreenerCategory,
+  CloudMarketScreenerItem,
+  CloudMarketScreenerPayload,
+} from "../../../api-client/types";
+import { hasProAccess } from "../shared/plan-access";
 
 const YAHOO_FINANCE_HOSTS = [
   "query2.finance.yahoo.com",
@@ -12,6 +20,7 @@ const CACHE_POLICY = {
   staleMs: 5 * 60 * 1000,
   expireMs: 60 * 60 * 1000,
 } as const;
+const YAHOO_METADATA_WAIT_MS = 1_500;
 
 const YAHOO_FINANCE_HEADERS = {
   "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
@@ -101,27 +110,34 @@ function writeCache<T>(key: string, data: T): void {
   });
 }
 
+/** A cached value plus whether it is a fallback rather than a fresh load. */
+export interface CachedResult<T> {
+  data: T;
+  stale: boolean;
+}
+
 async function loadCached<T>(
   key: string,
   fetcher: () => Promise<T>,
   options?: FetchCacheOptions,
-): Promise<T> {
-  if (options?.cache === false) return fetcher();
+): Promise<CachedResult<T>> {
+  if (options?.cache === false) return { data: await fetcher(), stale: false };
 
   const cached = readCache<T>(key);
-  if (!options?.forceRefresh && cached && !cached.stale) return cached.data;
+  if (!options?.forceRefresh && cached && !cached.stale) return { data: cached.data, stale: false };
 
-  const activeFetch = activeFetches.get(key) as Promise<T> | undefined;
+  const activeFetch = activeFetches.get(key) as Promise<CachedResult<T>> | undefined;
   if (activeFetch) return activeFetch;
 
   const fallback = cached ?? readCache<T>(key, { allowExpired: true });
   const fetchPromise = fetcher()
     .then((data) => {
       writeCache(key, data);
-      return data;
+      return { data, stale: false };
     })
     .catch((error) => {
-      if (fallback) return fallback.data;
+      // Serving the expired copy is right; hiding that it is expired is not.
+      if (fallback) return { data: fallback.data, stale: true };
       throw error;
     })
     .finally(() => {
@@ -152,6 +168,29 @@ export interface ScreenerQuote {
   dayHigh: number | undefined;
   dayLow: number | undefined;
   exchange: string;
+  lastUpdated?: number;
+}
+
+export type MarketMoversDataSource = "cloud" | "yahoo";
+
+export interface MarketMoversResult {
+  quotes: ScreenerQuote[];
+  source: MarketMoversDataSource;
+  stale: boolean;
+}
+
+export interface PreferredMarketMoverSources {
+  isCloudEligible(): boolean;
+  fetchCloud(
+    category: CloudMarketScreenerCategory,
+    count: number,
+    mode: "cache-first" | "refresh",
+  ): Promise<CloudMarketResponse<CloudMarketScreenerPayload>>;
+  fetchYahoo(
+    category: ScreenerCategory,
+    count: number,
+    options?: FetchCacheOptions,
+  ): Promise<CachedResult<ScreenerQuote[]>>;
 }
 
 export interface TrendingSymbol {
@@ -199,12 +238,12 @@ export function parseScreenerResponse(data: any): ScreenerQuote[] {
   }
 }
 
-export async function fetchScreener(
+export async function fetchScreenerResult(
   category: ScreenerCategory,
   count = 25,
   api: YahooScreenerApi = screenerApi,
   options?: FetchCacheOptions,
-): Promise<ScreenerQuote[]> {
+): Promise<CachedResult<ScreenerQuote[]>> {
   const load = async () => {
     const data = await api.fetchJson("/v1/finance/screener/predefined/saved", {
       formatted: "false",
@@ -215,10 +254,129 @@ export async function fetchScreener(
     });
     return parseScreenerResponse(data);
   };
-  if (!shouldUseCache(api, options)) return load();
+  if (!shouldUseCache(api, options)) return { data: await load(), stale: false };
   return loadCached(`screener:${category}:count=${count}`, load, options);
 }
 
+export async function fetchScreener(
+  category: ScreenerCategory,
+  count = 25,
+  api: YahooScreenerApi = screenerApi,
+  options?: FetchCacheOptions,
+): Promise<ScreenerQuote[]> {
+  return (await fetchScreenerResult(category, count, api, options)).data;
+}
+
+function cloudScreenerCategory(category: ScreenerCategory): CloudMarketScreenerCategory {
+  if (category === "day_gainers") return "gainers";
+  if (category === "day_losers") return "losers";
+  return "most-active";
+}
+
+function isCloudScreenerEligible(): boolean {
+  const user = apiClient.getCurrentUser();
+  return apiClient.isVerified() && hasProAccess(user);
+}
+
+const defaultPreferredMarketMoverSources: PreferredMarketMoverSources = {
+  isCloudEligible: isCloudScreenerEligible,
+  fetchCloud: (category, count, mode) => apiClient.getCloudMarketScreener(category, count, mode),
+  fetchYahoo: (category, count, options) => fetchScreenerResult(category, count, undefined, options),
+};
+
+function mergeCloudScreenerItem(
+  item: CloudMarketScreenerItem,
+  metadata?: ScreenerQuote,
+): ScreenerQuote {
+  return {
+    symbol: item.symbol,
+    name: item.name && item.name !== item.symbol
+      ? item.name
+      : metadata?.name ?? item.symbol,
+    price: item.price,
+    change: item.change,
+    changePercent: item.changePercent,
+    volume: item.volume,
+    avgVolume: metadata?.avgVolume ?? 0,
+    volumeRatio: metadata?.avgVolume
+      ? item.volume / metadata.avgVolume
+      : 0,
+    marketCap: metadata?.marketCap,
+    currency: item.currency || metadata?.currency || "USD",
+    fiftyTwoWeekHigh: item.high52w ?? metadata?.fiftyTwoWeekHigh,
+    fiftyTwoWeekLow: item.low52w ?? metadata?.fiftyTwoWeekLow,
+    dayHigh: item.dayHigh ?? metadata?.dayHigh,
+    dayLow: item.dayLow ?? metadata?.dayLow,
+    exchange: item.exchange || metadata?.exchange || "",
+    lastUpdated: item.lastUpdated,
+  };
+}
+
+async function bestEffortYahooMetadata(
+  request: Promise<CachedResult<ScreenerQuote[]>>,
+): Promise<ScreenerQuote[]> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      request.then((result) => result.data).catch(() => []),
+      new Promise<ScreenerQuote[]>((resolve) => {
+        timeout = setTimeout(() => resolve([]), YAHOO_METADATA_WAIT_MS);
+      }),
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+export async function fetchPreferredMarketMovers(
+  category: ScreenerCategory,
+  count = 25,
+  options?: FetchCacheOptions,
+  sources: PreferredMarketMoverSources = defaultPreferredMarketMoverSources,
+): Promise<MarketMoversResult> {
+  if (!sources.isCloudEligible()) {
+    const result = await sources.fetchYahoo(category, count, options);
+    return { quotes: result.data, source: "yahoo", stale: result.stale };
+  }
+
+  const yahooMetadata = sources.fetchYahoo(
+    category,
+    Math.max(count, 50),
+    options,
+  );
+  try {
+    const response = await sources.fetchCloud(
+      cloudScreenerCategory(category),
+      count,
+      options?.forceRefresh ? "refresh" : "cache-first",
+    );
+    if (
+      (response.status === "success" || response.status === "partial")
+      && response.data
+      && response.data.items.length > 0
+    ) {
+      const metadata = await bestEffortYahooMetadata(yahooMetadata);
+      const metadataBySymbol = new Map(metadata.map((quote) => [quote.symbol, quote]));
+      return {
+        quotes: response.data.items.map((item) => (
+          mergeCloudScreenerItem(item, metadataBySymbol.get(item.symbol))
+        )),
+        source: "cloud",
+        stale: response.stale === true || response.data.stale === true,
+      };
+    }
+  } catch {
+    // Yahoo remains the resilient fallback when Cloud is unavailable.
+  }
+
+  const fallback = await yahooMetadata;
+  return {
+    quotes: fallback.data,
+    source: "yahoo",
+    stale: fallback.stale,
+  };
+}
+
 export function parseTrendingResponse(data: any): TrendingSymbol[] {
   try {
     const quotes = data?.finance?.result?.[0]?.quotes;
@@ -246,7 +404,7 @@ export async function fetchTrending(
     return parseTrendingResponse(data);
   };
   if (!shouldUseCache(api, options)) return load();
-  return loadCached(`trending:US:count=${count}`, load, options);
+  return (await loadCached(`trending:US:count=${count}`, load, options)).data;
 }
 
 export const MARKET_SUMMARY_SYMBOLS = ["^GSPC", "^DJI", "^IXIC", "^RUT"] as const;

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

@@ -1,61 +1,37 @@
-import { Text } from "../../../ui";
-import { useRef, useEffect, useMemo, useState } from "react";
+import { Box } from "../../../ui";
 import { composeBuiltinPlugin, type PluginModule } from "../plugin-module";
 import { usePaneTicker } from "../../../state/app/context";
-import { colors } from "../../../theme/colors";
-import type { NewsArticle } from "../../../types/news-source";
 import { useArticleSummary, useResolvedEntryValue } from "../../../market-data/hooks";
 import { instrumentFromTicker } from "../../../market-data/request-types";
-import { useDebouncedPluginPaneState } from "../../runtime";
-import { FeedDataTableStackView, Spinner, type FeedDataTableItem } from "../../../components";
-import { useNewsArticles } from "../../../news/hooks";
+import { useDebouncedPluginPaneState, usePluginPaneState } from "../../runtime";
+import { EmptyState } from "../../../components";
+import { useLoadNewsStory, useNewsArticles } from "../../../news/hooks";
 import { newsWireModule } from "./wire";
+import { NewsDetailView, useNewsArticleDetail } from "./wire/news/detail-view";
+import {
+  NewsArticleStackView,
+  newsTableStatusContent,
+  type NewsSortPreference,
+} from "./wire/news/table";
 import { useNewsArticleFooter } from "./wire/news/footer";
 import { usePersistedNewsArticles } from "./wire/persisted-articles";
 import { useNewsReadState } from "./wire/read-state";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 
 const NEWS_ITEM_LIMIT = 50;
-
-function getFeedItems(
-  news: NewsArticle[],
-  selectedUrl: string | undefined,
-  summaryCache: Map<string, string>,
-  loadingSummary: boolean,
-): FeedDataTableItem[] {
-  return news.map((item) => {
-    const preview = summaryCache.get(item.url) ?? item.summary ?? undefined;
-    const isSelected = item.url === selectedUrl;
-    return {
-      id: item.id,
-      eyebrow: item.source,
-      title: item.title,
-      timestamp: item.publishedAt,
-      detailTitle: item.title,
-      detailMeta: [
-        item.source,
-        `Published ${item.publishedAt.toLocaleString("en-US", {
-          month: "short",
-          day: "numeric",
-          year: "numeric",
-          hour: "numeric",
-          minute: "2-digit",
-        })}`,
-      ],
-      detailBody: isSelected
-        ? preview ?? (loadingSummary ? "Loading preview..." : "No preview available.")
-        : preview ?? "",
-      detailNote: item.url,
-    };
-  });
-}
+const DEFAULT_SORT: NewsSortPreference = { columnId: "time", direction: "desc" };
 
 function TickerNewsView({ width, height, focused }: { width: number; height: number; focused: boolean }) {
   const { ticker } = usePaneTicker();
-  const selectionKey = `selectedIdx:${ticker?.metadata.ticker ?? "none"}`;
-  const [selectedIdx, setSelectedIdx] = useDebouncedPluginPaneState<number>(selectionKey, 0);
-  const [summaryCache, setSummaryCache] = useState<Map<string, string>>(new Map());
-  const summaryFetchRef = useRef(0);
+  const symbol = ticker?.metadata.ticker ?? "none";
+  const [selectedArticleId, setSelectedArticleId] = useDebouncedPluginPaneState<string | null>(
+    `selectedArticleId:${symbol}`,
+    null,
+  );
+  const [sortPreference, setSortPreference] = usePluginPaneState<NewsSortPreference>(
+    "ticker-news:sort",
+    DEFAULT_SORT,
+  );
   const instrument = instrumentFromTicker(ticker, ticker?.metadata.ticker ?? null);
   const newsState = useNewsArticles(instrument ? {
     feed: "ticker",
@@ -64,81 +40,84 @@ function TickerNewsView({ width, height, focused }: { width: number; height: num
     tickerTier: "primary",
     limit: NEWS_ITEM_LIMIT,
   } : null);
-  const liveNews = newsState.articles;
   const news = usePersistedNewsArticles(
     `articles:${instrument?.symbol ?? "none"}:${instrument?.exchange ?? ""}`,
-    liveNews,
+    newsState.articles,
   );
   const { readArticleIds, markArticleRead } = useNewsReadState();
-  const [openItemId, setOpenItemId] = useState<string | null>(null);
-  const loading = newsState.phase === "loading" || (newsState.phase === "refreshing" && news.length === 0);
-  const error = newsState.phase === "error" ? newsState.error ?? "Failed to load news" : null;
-
-  useEffect(() => {
-    summaryFetchRef.current += 1;
-    setSummaryCache(new Map());
-  }, [ticker?.metadata.ticker]);
+  const loadNewsStory = useLoadNewsStory();
+  const { detailArticle, openArticle, closeDetail } = useNewsArticleDetail(news, loadNewsStory);
+  const loading = newsState.phase === "loading"
+    || (newsState.phase === "refreshing" && news.length === 0);
+  const error = newsState.error;
 
-  const selected = news[selectedIdx];
-  const openArticle = openItemId
-    ? news.find((article) => article.id === openItemId) ?? null
-    : null;
-  const cachedSelectedSummary = selected ? summaryCache.get(selected.url) : undefined;
   const articleSummaryEntry = useArticleSummary(
-    selected && !selected.summary && !cachedSelectedSummary ? selected.url : null,
+    detailArticle && !detailArticle.summary ? detailArticle.url : null,
   );
-  const selectedSummary = useResolvedEntryValue(articleSummaryEntry);
-  const loadingSummary = articleSummaryEntry?.phase === "loading" || articleSummaryEntry?.phase === "refreshing";
-
-  useEffect(() => {
-    if (!selected?.summary) return;
-    const summary = selected.summary;
-    setSummaryCache((prev) => prev.has(selected.url) ? prev : new Map(prev).set(selected.url, summary));
-  }, [selected?.summary, selected?.url]);
-
-  useEffect(() => {
-    if (!selected?.url || !selectedSummary) return;
-    setSummaryCache((prev) => new Map(prev).set(selected.url, selectedSummary));
-  }, [selected?.url, selectedSummary]);
-
-  useEffect(() => {
-    if (news.length > 0 && selectedIdx >= news.length) {
-      setSelectedIdx(Math.max(0, news.length - 1));
-    }
-  }, [news.length, selectedIdx, setSelectedIdx]);
+  const fetchedSummary = useResolvedEntryValue(articleSummaryEntry);
+  const loadingSummary = articleSummaryEntry?.phase === "loading"
+    || articleSummaryEntry?.phase === "refreshing";
+  const detailWithSummary = detailArticle && !detailArticle.summary && fetchedSummary
+    ? { ...detailArticle, summary: fetchedSummary }
+    : detailArticle;
 
   useNewsArticleFooter({
     registrationId: "news",
     focused,
-    article: openArticle,
-    loading,
+    article: detailArticle,
+    // Stale rows stay on screen during a refresh or a failure, so the pane says
+    // so in the footer instead of replacing them.
+    loading: loading && news.length > 0,
     error,
     info: loadingSummary
       ? [{ id: "summary", parts: [{ text: "summary loading", tone: "muted" as const }] }]
       : undefined,
   });
 
-  if (!ticker) return <Text fg={colors.textDim}>Select a ticker to view news.</Text>;
-  if (loading && news.length === 0) return <Spinner label="Loading news..." />;
-  if (error) return <Text fg={colors.textDim}>Error: {error}</Text>;
-  if (news.length === 0) return <Text fg={colors.textDim}>No news available for {ticker.metadata.ticker}.</Text>;
-
-  const items = getFeedItems(news, selected?.url, summaryCache, loadingSummary);
+  if (!ticker) {
+    return (
+      <Box paddingX={1} paddingY={1}>
+        <EmptyState title="No ticker selected." message="Pick a ticker to load its news." />
+      </Box>
+    );
+  }
 
   return (
-    <FeedDataTableStackView
-      width={width}
-      height={height}
+    <NewsArticleStackView
+      articles={news}
       focused={focused}
-      items={items}
-      selectedIdx={selectedIdx}
-      onSelect={setSelectedIdx}
-      isItemRead={(item) => readArticleIds.has(item.id)}
-      onOpenItem={(item) => markArticleRead(item.id)}
-      onOpenItemIdChange={setOpenItemId}
-      sourceLabel="Source"
-      titleLabel="Headline"
-      emptyStateTitle="No news."
+      width={width}
+      rootHeight={height}
+      readArticleIds={readArticleIds}
+      selectedArticleId={selectedArticleId}
+      setSelectedArticleId={setSelectedArticleId}
+      sortPreference={sortPreference}
+      setSortPreference={setSortPreference}
+      onOpenArticle={openArticle}
+      onArticleRead={markArticleRead}
+      detailOpen={!!detailWithSummary}
+      onBack={closeDetail}
+      detailContent={detailWithSummary ? (
+        <NewsDetailView
+          item={detailWithSummary}
+          focused={focused}
+          width={width}
+          showTitle={false}
+        />
+      ) : (
+        <Box flexGrow={1} />
+      )}
+      detailTitle={detailWithSummary?.title}
+      columns={["time", "source", "title", "categories", "sentiment"]}
+      emptyContent={newsTableStatusContent({
+        loading,
+        error,
+        subject: "News",
+        emptyTitle: `No news for ${ticker.metadata.ticker}`,
+        emptyMessage: "Stories appear as sources publish them.",
+      })}
+      emptyStateTitle={`No news for ${ticker.metadata.ticker}`}
+      emptyStateHint="Stories appear as sources publish them."
     />
   );
 }

package/src/plugins/builtin/news/wire/article-search.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import type { NewsArticle } from "../../../../news/types";
+import {
+  looksLikeArticleQuery,
+  searchNewsArticles,
+  tokenizeArticleQuery,
+} from "./article-search";
+
+function article(overrides: Partial<NewsArticle> & Pick<NewsArticle, "id" | "title" | "source">): NewsArticle {
+  return {
+    url: `https://example.com/${overrides.id}`,
+    publishedAt: new Date("2026-08-14T12:00:00Z"),
+    topic: "general",
+    topics: [],
+    sectors: [],
+    categories: [],
+    tickers: [],
+    scores: { importance: 50, urgency: 0, marketImpact: 0, novelty: 0, confidence: 0 },
+    isBreaking: false,
+    isDeveloping: false,
+    importance: 50,
+    ...overrides,
+  };
+}
+
+const hormuz = article({
+  id: "hormuz",
+  title: "Iran Threatens to Close the Strait of Hormuz",
+  source: "Reuters",
+  summary: "Shipping risk rises as Tehran warns it may shut the strait.",
+  publishedAt: new Date("2026-08-14T18:00:00Z"),
+});
+
+const other = article({
+  id: "fed",
+  title: "Fed holds rates as inflation cools",
+  source: "CNBC Top News",
+  publishedAt: new Date("2026-08-13T12:00:00Z"),
+});
+
+describe("looksLikeArticleQuery", () => {
+  test("treats article, news, and ART lookups as article searches", () => {
+    expect(looksLikeArticleQuery("article on the strait")).toBe(true);
+    expect(looksLikeArticleQuery("ART hormuz")).toBe(true);
+    expect(looksLikeArticleQuery("open press story")).toBe(true);
+    expect(looksLikeArticleQuery("ADI")).toBe(false);
+    expect(looksLikeArticleQuery("nvda")).toBe(false);
+  });
+});
+
+describe("searchNewsArticles", () => {
+  test("matches headlines after dropping filler and intent words", () => {
+    expect(tokenizeArticleQuery("article on the strait of hormuz")).toEqual(["strait", "hormuz"]);
+    const matches = searchNewsArticles([hormuz, other], "article on the strait of hormuz");
+    expect(matches.map((item) => item.id)).toEqual(["hormuz"]);
+  });
+
+  test("returns most recent articles when the query is only an intent word", () => {
+    const matches = searchNewsArticles([other, hormuz], "article");
+    expect(matches.map((item) => item.id)).toEqual(["hormuz", "fed"]);
+  });
+
+  test("strips the ART command prefix so local headlines match immediately", () => {
+    const trump = article({
+      id: "trump",
+      title: "Trump administration pauses contentious trade talks",
+      source: "AP",
+    });
+    expect(tokenizeArticleQuery("art trum")).toEqual(["trum"]);
+    expect(searchNewsArticles([trump, other], "ART trum").map((item) => item.id)).toEqual(["trump"]);
+  });
+});

package/src/plugins/builtin/news/wire/article-search.ts

@@ -0,0 +1,140 @@
+import type { NewsArticle, NewsQuery } from "../../../../news/types";
+import { getSharedNewsService } from "../../../../news/hooks";
+
+const ARTICLE_SEARCH_LIMIT = 8;
+
+const STOPWORDS = new Set([
+  "a",
+  "an",
+  "the",
+  "on",
+  "of",
+  "in",
+  "to",
+  "for",
+  "and",
+  "or",
+  "from",
+  "with",
+  "about",
+  "by",
+  "at",
+  "as",
+  "is",
+  "are",
+  "was",
+  "be",
+]);
+
+const INTENT_WORDS = new Set([
+  "article",
+  "articles",
+  "news",
+  "headline",
+  "headlines",
+  "story",
+  "stories",
+  "rss",
+  "feed",
+  "feeds",
+  "press",
+]);
+
+const COMMAND_WORDS = new Set([
+  "open",
+  "read",
+  "show",
+  "find",
+  "search",
+  "please",
+  "me",
+  "latest",
+  "recent",
+  "lookup",
+  "look",
+  "up",
+]);
+
+/** Pulls the freshest slice of the global feed to search over. */
+export const ARTICLE_SEARCH_QUERY: NewsQuery = { feed: "latest", limit: 200 };
+
+export function tokenizeArticleQuery(query: string): string[] {
+  // `ART trump` is the command prefix plus a topic — "art" is not a search term.
+  const withoutArtPrefix = query.replace(/^\s*art\b/i, " ");
+  return withoutArtPrefix
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter((token) => (
+      token.length >= 2
+      && !STOPWORDS.has(token)
+      && !INTENT_WORDS.has(token)
+      && !COMMAND_WORDS.has(token)
+    ));
+}
+
+export function looksLikeArticleQuery(query: string): boolean {
+  const tokens = query.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+  if (tokens.some((token) => INTENT_WORDS.has(token))) return true;
+  return /^\s*art\b/i.test(query);
+}
+
+export function scoreArticleMatch(article: NewsArticle, tokens: readonly string[]): number {
+  if (tokens.length === 0) return 0;
+  const title = article.title.toLowerCase();
+  const source = article.source.toLowerCase();
+  const haystack = [
+    title,
+    source,
+    article.summary ?? "",
+    ...article.topics,
+    ...article.categories,
+    ...article.tickers,
+  ].join(" ").toLowerCase();
+
+  let score = 0;
+  for (const token of tokens) {
+    if (title.includes(token)) score += 10;
+    else if (source.includes(token)) score += 6;
+    else if (haystack.includes(token)) score += 3;
+    else return 0;
+  }
+  return score;
+}
+
+export function searchNewsArticles(
+  articles: readonly NewsArticle[],
+  query: string,
+  limit = ARTICLE_SEARCH_LIMIT,
+): NewsArticle[] {
+  const tokens = tokenizeArticleQuery(query);
+  if (tokens.length === 0) {
+    return [...articles]
+      .sort((left, right) => right.publishedAt.getTime() - left.publishedAt.getTime())
+      .slice(0, limit);
+  }
+
+  return articles
+    .map((article) => ({ article, score: scoreArticleMatch(article, tokens) }))
+    .filter((entry) => entry.score > 0)
+    .sort((left, right) => {
+      if (right.score !== left.score) return right.score - left.score;
+      return right.article.publishedAt.getTime() - left.article.publishedAt.getTime();
+    })
+    .slice(0, limit)
+    .map((entry) => entry.article);
+}
+
+/** Headlines already sitting in the shared news pool (firehose/RSS/breaking). */
+export function cachedNewsArticles(): NewsArticle[] {
+  const service = getSharedNewsService();
+  if (!service) return [];
+  const pooled = service.getFirehose(undefined, 500);
+  if (pooled.length > 0) return pooled;
+  return service.getQueryState(ARTICLE_SEARCH_QUERY).articles;
+}
+
+export async function loadNewsArticles(): Promise<NewsArticle[]> {
+  const service = getSharedNewsService();
+  if (!service) return [];
+  return (await service.load(ARTICLE_SEARCH_QUERY)).articles;
+}