gloomberb 0.16.1 → 0.16.2

package/src/plugins/builtin/earnings-ripple/client.ts

@@ -1,60 +1,133 @@
 import type { EarningsCalendarPayload, EarningsCalendarQuery } from "../../../api-client/earnings";
 import type { SupplyChainPayload } from "../../../api-client/supply-chain";
+import { DEFAULT_GRAPH_OPTIONS, type GraphOptions, type GraphPayload } from "../../../api-client/supply-chain-graph";
 import { errorMessage } from "../../../utils/errors";
 import { addDays, newYorkToday } from "../earnings/board-model";
 import { loadEarningsBoard } from "../earnings/client";
 import { loadSupplyChain } from "../supply-chain/client";
-import { projectRipple, rippleCompanyTickers, RIPPLE_DAYS, type RippleRow } from "./model";
+import { cachedGraph, loadGraph } from "../supply-chain/graph-client";
+import { projectRipple, projectSecondHop, rippleCompanyTickers, RIPPLE_DAYS, secondHopLinks, type RippleRow, type SecondHopRow } from "./model";
 
 export interface RippleSources {
   supplyChain(symbol: string): Promise<SupplyChainPayload>;
   calendar(query: EarningsCalendarQuery): Promise<EarningsCalendarPayload>;
+  /** SPLC's graph, which returns both hops around a holding in one call. Absent when the account sees one hop only. */
+  graph?(symbol: string, options: GraphOptions): Promise<GraphPayload>;
 }
 
+/**
+ * The graph query behind the 2 hops tab. Supplier and customer links only, and
+ * only evidence from filings, company announcements and calls (graph classes
+ * structured and primary), the tiers the 1 hop tab's disclosures are read with.
+ * The server filters before it ranks and caps each direction, so news and
+ * partner routes cannot use up the 50 companies a direction returns.
+ */
+const RIPPLE_GRAPH_OPTIONS: GraphOptions = { ...DEFAULT_GRAPH_OPTIONS, depth: 2, roles: ["customer", "supplier"], tiers: ["structured", "primary"] };
+
+/**
+ * What opens SPLC's Path view on a 2 hops row: from the holding to the company
+ * that reports, on RIPL's own query in the row's direction, so the route the
+ * row shows is the one Path lists.
+ */
+export function rippleRouteSettings(row: Pick<SecondHopRow, "company" | "link">): Record<string, string> {
+  return { tab: "path", to: row.company, depth: String(RIPPLE_GRAPH_OPTIONS.depth), direction: row.link === "supplier" ? "upstream" : "downstream",
+    roles: RIPPLE_GRAPH_OPTIONS.roles.join(","), tiers: RIPPLE_GRAPH_OPTIONS.tiers.join(",") };
+}
+
+interface Failure { symbol: string; error: string }
+
 export interface RippleSnapshot {
   rows: RippleRow[];
   /** Holdings whose disclosures could not be read, with the reason. */
-  failures: { symbol: string; error: string }[];
+  failures: Failure[];
   /** Holdings whose disclosures the free preview cut short, so a missing link may only be hidden. */
   truncated: string[];
+  /**
+   * Companies two hops away, when asked for. `locked`: the account sees one hop
+   * only. `truncated`: holdings whose graph search stopped at a limit, with the
+   * server's reasons, so a company missing there may only be cut off.
+   */
+  secondHop: { rows: SecondHopRow[]; failures: Failure[]; truncated: { symbol: string; reasons: string[] }[]; locked: boolean } | null;
   stale: boolean;
   from: string;
   to: string;
 }
 
-/** The same caches SPLC and ERN fill, so opening either pane after this costs nothing. */
-export function cachedRippleSources(accessKey: string, force = false): RippleSources & { staleFlags: boolean[] } {
+/**
+ * The same caches SPLC and ERN fill, so opening either pane after this costs
+ * nothing. `graph`: no graph source, graphs read through the cache, or graphs
+ * from the cache alone (fetched only when missing) while 2 hops is not on screen.
+ */
+export function cachedRippleSources(accessKey: string, force = false, graph: "off" | "load" | "cached" = "off"): RippleSources & { staleFlags: boolean[] } {
   const staleFlags: boolean[] = [];
   return {
     staleFlags,
     supplyChain: async (symbol) => { const result = await loadSupplyChain(symbol, accessKey, force); staleFlags.push(result.stale); return result.payload; },
     calendar: async (query) => { const result = await loadEarningsBoard(query, force); staleFlags.push(result.stale); return result.payload; },
+    // Cached by the full query, apart from SPLC Graph's default one.
+    ...(graph !== "off" ? { graph: async (symbol: string, options: GraphOptions) => {
+      const cached = graph === "cached" ? cachedGraph(symbol, "", options, accessKey) : null;
+      const result = cached ?? await loadGraph(symbol, "", options, accessKey, force); staleFlags.push(result.stale); return result.payload;
+    } } : {}),
   };
 }
 
 const CONCURRENCY = 6;
 
-export async function loadRipple(holdings: readonly string[], sources: RippleSources & { staleFlags?: boolean[] }, now = new Date()): Promise<RippleSnapshot> {
+async function eachLimited(symbols: readonly string[], load: (symbol: string) => Promise<void>) {
+  const queue = [...symbols];
+  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
+    for (let symbol = queue.shift(); symbol; symbol = queue.shift()) await load(symbol);
+  }));
+}
+
+const locked = () => ({ graphs: new Map<string, GraphPayload>(), failures: [] as Failure[], locked: true });
+const isPreview = (graphs: ReadonlyMap<string, GraphPayload>) => [...graphs.values()].some((graph) => graph.access === "preview");
+
+/** One graph call per holding. The first answer says whether the account sees two hops; a one-hop preview skips the rest. */
+async function loadGraphs(holdings: readonly string[], graph: NonNullable<RippleSources["graph"]>) {
+  const graphs = new Map<string, GraphPayload>();
+  const failures: Failure[] = [];
+  const load = async (symbol: string) => {
+    try { graphs.set(symbol, await graph(symbol, RIPPLE_GRAPH_OPTIONS)); }
+    catch (error) { failures.push({ symbol, error: errorMessage(error) }); }
+  };
+  const [first, ...rest] = holdings;
+  if (first) await load(first);
+  if (isPreview(graphs)) return locked();
+  await eachLimited(rest, load);
+  // Only when the first holding failed can a preview get this far.
+  if (isPreview(graphs)) return locked();
+  return { graphs, failures: failures.sort((a, b) => a.symbol.localeCompare(b.symbol)), locked: false };
+}
+
+export async function loadRipple(holdings: readonly string[], sources: RippleSources & { staleFlags?: boolean[] }, now = new Date(), { secondHop = false } = {}): Promise<RippleSnapshot> {
   const from = newYorkToday(now);
   const to = addDays(from, RIPPLE_DAYS);
+  const symbols = [...new Set(holdings.map((symbol) => symbol.toUpperCase()))];
   const chains = new Map<string, SupplyChainPayload>();
-  const failures: RippleSnapshot["failures"] = [];
-  const queue = [...new Set(holdings.map((symbol) => symbol.toUpperCase()))];
-  await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
-    for (let symbol = queue.shift(); symbol; symbol = queue.shift()) {
-      try { chains.set(symbol, await sources.supplyChain(symbol)); }
-      catch (error) { failures.push({ symbol, error: errorMessage(error) }); }
-    }
-  }));
-  const companies = rippleCompanyTickers(chains);
+  const failures: Failure[] = [];
+  await eachLimited(symbols, async (symbol) => {
+    try { chains.set(symbol, await sources.supplyChain(symbol)); }
+    catch (error) { failures.push({ symbol, error: errorMessage(error) }); }
+  });
+  const second = !secondHop ? null : sources.graph ? await loadGraphs(symbols, sources.graph) : locked();
+  const graphs = second?.graphs ?? new Map<string, GraphPayload>();
+  const companies = [...rippleCompanyTickers(chains), ...secondHopLinks(chains, graphs).map((link) => link.company.ticker!.toUpperCase())];
   const reports: EarningsCalendarPayload["reports"] = [];
   if (companies.length) {
-    const symbols = [...new Set([...companies, ...holdings.map((symbol) => symbol.toUpperCase())])].sort();
-    for (let offset = 0; offset < symbols.length; offset += 200) {
-      const payload = await sources.calendar({ from, to, perDay: 0, symbols: symbols.slice(offset, offset + 200) });
+    const calendarSymbols = [...new Set([...companies, ...symbols])].sort();
+    for (let offset = 0; offset < calendarSymbols.length; offset += 200) {
+      const payload = await sources.calendar({ from, to, perDay: 0, symbols: calendarSymbols.slice(offset, offset + 200) });
       reports.push(...payload.reports);
     }
   }
   const truncated = [...chains].filter(([, chain]) => chain.truncated).map(([symbol]) => symbol).sort();
-  return { rows: projectRipple(chains, reports), failures, truncated, stale: !!sources.staleFlags?.some(Boolean), from, to };
+  return {
+    rows: projectRipple(chains, reports), failures, truncated,
+    secondHop: second ? { rows: projectSecondHop(chains, graphs, reports), failures: second.failures, locked: second.locked,
+      truncated: [...graphs].filter(([, graph]) => graph.truncated || !graph.search.complete)
+        .map(([symbol, graph]) => ({ symbol, reasons: graph.search.reasons })).sort((a, b) => a.symbol.localeCompare(b.symbol)) } : null,
+    stale: !!sources.staleFlags?.some(Boolean), from, to,
+  };
 }

package/src/plugins/builtin/earnings-ripple/headless.ts

@@ -1,35 +1,55 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchEarningsCalendar } from "../earnings/client";
 import { fetchSupplyChain } from "../supply-chain/client";
+import { fetchSupplyGraph } from "../supply-chain/graph-client";
 import { loadRipple } from "./client";
-import { revenueOwner } from "./model";
+import { hopLabel, revenueOwner } from "./model";
 
 const percent = (value: unknown) => typeof value === "number" ? `${(value * 100).toFixed(1)}%` : "--";
 
 export const earningsRippleHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  freshness: { source: "SEC filings and Gloom Cloud", status: "not-a-feed", basis: "filings and earnings calendar" },
   argument: { kind: "symbol-list", placeholder: "tickers", description: "Holdings to check against their customers' and suppliers' report dates.", minimum: 1, maximum: 60 },
-  options: [],
+  options: [{ key: "tab", type: "enum", settingKey: "tab", defaultValue: "direct", values: [{ value: "direct" }, { value: "two-hop" }],
+    description: "Direct customers and suppliers, or also companies two hops away (Pro)." }],
   describe: (args) => `RIPL ${args.symbols.join(", ")}`,
-  discovery: { screenshotReadiness: "live-dom", limitations: ["Customers each holding names in its own US filings, and suppliers whose US filings name it, with a share of revenue."] },
+  discovery: { screenshotReadiness: "live-dom", limitations: ["Customers each holding names in its own US filings, and suppliers whose US filings name it, with a share of revenue.",
+    "Two hops: a supplier's supplier or a customer's customer from the supply chain graph, read from filings, company announcements and calls only, Pro only; companies already one hop away are left out."] },
   async load(args, ctx) {
+    const secondHop = args.options.tab === "two-hop";
     const snapshot = await loadRipple(args.symbols, {
       supplyChain: (symbol) => fetchSupplyChain(symbol, ctx.apiClient),
       calendar: (query) => fetchEarningsCalendar(query, ctx.apiClient),
-    });
+      graph: (symbol, options) => fetchSupplyGraph(symbol, options, "", ctx.apiClient),
+    }, undefined, { secondHop });
     ctx.signal.throwIfAborted();
+    const second = snapshot.secondHop;
     return {
       sections: [{ title: `Customers and suppliers reporting ${snapshot.from} to ${snapshot.to}`, columns: [
         { key: "date", header: "Date" }, { key: "timing", header: "Time" }, { key: "company", header: "Reports" }, { key: "link", header: "Link" },
         { key: "holding", header: "Holding" }, { key: "pctOfRevenue", header: "Revenue %" }, { key: "revenueOf", header: "Of" }, { key: "averageMove", header: "Avg move", format: percent },
         { key: "holdingDate", header: "Holding reports" }, { key: "period", header: "Filing period" },
-      ], rows: snapshot.rows.map((row) => ({ ...row, timing: row.timing?.toUpperCase() ?? null, link: row.link === "customer" ? "customer of" : "supplier to", revenueOf: revenueOwner(row) })) }],
-      complete: snapshot.failures.length === 0 && snapshot.truncated.length === 0,
+      ], rows: snapshot.rows.map((row) => ({ ...row, timing: row.timing?.toUpperCase() ?? null, link: row.link === "customer" ? "customer of" : "supplier to", revenueOf: revenueOwner(row) })) },
+      ...(second && !second.locked ? [{ title: `Two hops away, reporting ${snapshot.from} to ${snapshot.to}`, columns: [
+        { key: "date", header: "Date" }, { key: "timing", header: "Time" }, { key: "company", header: "Reports" }, { key: "link", header: "Link" },
+        { key: "via", header: "Via" }, { key: "holding", header: "Holding" }, { key: "hop1", header: "Holding to via" }, { key: "hop2", header: "Via to company" },
+        { key: "exposure", header: "Estimated exposure" }, { key: "averageMove", header: "Avg move", format: percent }, { key: "holdingDate", header: "Holding reports" },
+      ], rows: second.rows.map((row) => ({ ...row, timing: row.timing?.toUpperCase() ?? null, link: row.link === "customer" ? "customer's customer" : "supplier's supplier",
+        hop1: hopLabel(row.hops[0]), hop2: hopLabel(row.hops[1]) })) }] : []),
+      ],
+      complete: snapshot.failures.length === 0 && snapshot.truncated.length === 0 && !second?.locked && !second?.failures.length && !second?.truncated.length,
       unavailableSymbols: snapshot.failures.map((failure) => failure.symbol),
       // Same wording as SPLC: the preview's cut hides relationships, it does not mean there are none.
       errors: [...snapshot.failures.map((failure) => `${failure.symbol}: ${failure.error}`),
-        ...(snapshot.truncated.length ? ["Additional relationships need Gloom Pro"] : [])],
-      metadata: { from: snapshot.from, to: snapshot.to, truncated: snapshot.truncated, unit: "percent of the seller's revenue, as the seller's filing discloses it", methodology: "docs/research-data.md#earnings-ripple" },
+        ...(snapshot.truncated.length ? ["Additional relationships need Gloom Pro"] : []),
+        ...(second?.locked ? ["Companies two hops away need Gloom Pro"] : []),
+        ...(second?.failures ?? []).map((failure) => `${failure.symbol} graph: ${failure.error}`),
+        // As SPLC words it: the graph stopped at a limit, so companies two hops away may be missing.
+        ...(second?.truncated ?? []).map(({ symbol, reasons }) => `${symbol}: ${reasons.length
+          ? `Graph search incomplete: ${reasons.join(", ").replaceAll("_", " ")}` : "Graph results are truncated"}`)],
+      metadata: { from: snapshot.from, to: snapshot.to, truncated: snapshot.truncated, ...(second ? { twoHopTruncated: second.truncated.map(({ symbol }) => symbol) } : {}),
+        unit: "percent of the seller's revenue, as the seller's filing discloses it", methodology: "docs/research-data.md#earnings-ripple" },
     };
   },
 };

package/src/plugins/builtin/earnings-ripple/index.tsx

@@ -18,8 +18,8 @@ export const earningsRippleModule: PluginModule = {
   }],
   paneTemplates: [{
     id: "earnings-ripple-pane", paneId: "earnings-ripple", label: "Earnings Ripple",
-    description: "Customers of your holdings that report soon, with the share of each holding's revenue they make up.",
-    keywords: ["ripl", "ripple", "earnings", "customers", "supply chain", "exposure", "read-through"],
+    description: "Customers and suppliers of your holdings that report soon, with the disclosed revenue share, and with Pro the companies two hops away.",
+    keywords: ["ripl", "ripple", "earnings", "customers", "supply chain", "exposure", "read-through", "suppliers", "two hop", "second order"],
     shortcut: { prefix: "RIPL", argPlaceholder: "tickers", argKind: "ticker-list", argOptional: true, openWithoutArg: true },
     headless: earningsRippleHeadless,
     canCreate: () => true,

package/src/plugins/builtin/earnings-ripple/model.ts

@@ -1,7 +1,9 @@
 import type { EarningsCalendarReport, EarningsTiming } from "../../../api-client/earnings";
-import type { SupplyChainPayload, SupplyRow } from "../../../api-client/supply-chain";
+import type { SupplyChainPayload, SupplyEntity, SupplyRow } from "../../../api-client/supply-chain";
+import type { GraphPath, GraphPayload } from "../../../api-client/supply-chain-graph";
 import { isUsListingExchange } from "../../../utils/exchanges";
 import { MIN_AVERAGE_REPORTS } from "../earnings/board-model";
+import { exposureLabel } from "../supply-chain/graph-model";
 
 /** Days ahead the calendar is read. */
 export const RIPPLE_DAYS = 30;
@@ -71,18 +73,24 @@ export function rippleCompanyTickers(chains: ReadonlyMap<string, SupplyChainPayl
   return [...companies];
 }
 
-/**
- * Customers a holding names in its own filings (`says`), and suppliers whose
- * filings name the holding as a customer (`names`), that report in the
- * calendar: soonest first, then by the share.
- */
-export function projectRipple(chains: ReadonlyMap<string, SupplyChainPayload>, reports: readonly EarningsCalendarReport[]): RippleRow[] {
+/** Each company's soonest report in the window. */
+function nextReports(reports: readonly EarningsCalendarReport[]) {
   const next = new Map<string, EarningsCalendarReport>();
   for (const report of reports) {
     const key = report.symbol.toUpperCase();
     const current = next.get(key);
     if (!current || report.date < current.date) next.set(key, report);
   }
+  return next;
+}
+
+/**
+ * Customers a holding names in its own filings (`says`), and suppliers whose
+ * filings name the holding as a customer (`names`), that report in the
+ * calendar: soonest first, then by the share.
+ */
+export function projectRipple(chains: ReadonlyMap<string, SupplyChainPayload>, reports: readonly EarningsCalendarReport[]): RippleRow[] {
+  const next = nextReports(reports);
   const rows: RippleRow[] = [];
   for (const [holding, chain] of chains) {
     for (const { row, link } of rippleLinks(chain)) {
@@ -96,3 +104,85 @@ export function projectRipple(chains: ReadonlyMap<string, SupplyChainPayload>, r
   }
   return rows.sort((a, b) => a.date.localeCompare(b.date) || b.pctOfRevenue - a.pctOfRevenue || a.holding.localeCompare(b.holding));
 }
+
+/** One hop of a two-hop route, with the share the reporting company's filing discloses. */
+export interface RippleHop {
+  /** Whose figure it is: the reporting company. */
+  owner: string;
+  pct: number | null;
+  basis: SupplyRow["pctBasis"];
+  scoped: boolean;
+}
+
+export interface SecondHopRow extends Omit<RippleRow, "pctOfRevenue" | "pctScope" | "period"> {
+  /** The company between the holding and the one that reports. */
+  via: string;
+  viaName: string;
+  /** Holding to via, then via to the company. */
+  hops: [RippleHop, RippleHop];
+  /** Chained estimate along the route, when every hop's figure is compatible. */
+  exposure: string | null;
+}
+
+const entityLabel = (entity: SupplyEntity) => entity.ticker?.toUpperCase() ?? entity.name;
+
+interface SecondHopLink { holding: string; company: SupplyEntity; via: SupplyEntity; link: "customer" | "supplier"; path: GraphPath; graph: GraphPayload }
+
+/**
+ * Companies two disclosed hops from each holding: a supplier's supplier
+ * (upstream) or a customer's customer (downstream). Anyone the holding already
+ * has a direct link with, in its disclosures or in the graph, is hop 1 and is
+ * left out, as are companies outside the US calendar. One row per holding and
+ * company: the higher-scoring route when both directions reach it.
+ */
+export function secondHopLinks(chains: ReadonlyMap<string, SupplyChainPayload>, graphs: ReadonlyMap<string, GraphPayload>): SecondHopLink[] {
+  const result: SecondHopLink[] = [];
+  for (const [holding, graph] of graphs) {
+    const chain = chains.get(holding);
+    const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+    const reaches = [...graph.upstream, ...graph.downstream];
+    const direct = new Set([holding.toUpperCase(),
+      ...[...chain?.says ?? [], ...chain?.names ?? []].flatMap((row) => row.counterparty.ticker ? [row.counterparty.ticker.toUpperCase()] : []),
+      ...reaches.filter((reach) => reach.hops === 1).flatMap((reach) => nodes.get(reach.entityId)?.ticker?.toUpperCase() ?? [])]);
+    const best = new Map<string, SecondHopLink>();
+    for (const reach of reaches) {
+      const path = reach.shortestPath;
+      const company = nodes.get(reach.entityId);
+      const via = nodes.get(path.nodeIds[1] ?? "");
+      const ticker = company?.ticker?.toUpperCase();
+      if (reach.hops !== 2 || path.hops !== 2 || !company || !via || !ticker || company.aggregate || direct.has(ticker)) continue;
+      if (company.exchange && !isUsListingExchange(company.exchange)) continue;
+      const current = best.get(ticker);
+      if (!current || path.score > current.path.score) best.set(ticker, { holding, company, via, link: reach.direction === "upstream" ? "supplier" : "customer", path, graph });
+    }
+    result.push(...best.values());
+  }
+  return result;
+}
+
+function hopShare(graph: GraphPayload, linkId: string): RippleHop {
+  const link = graph.links.find((entry) => entry.id === linkId);
+  const evidence = link?.evidence.find((item) => item.id === link.primaryEvidenceId);
+  return { owner: evidence ? entityLabel(evidence.reporter) : "--", pct: evidence?.pctOfRevenue ?? null, basis: evidence?.pctBasis ?? null, scoped: !!evidence?.pctScope };
+}
+
+/** `30% of TSM`, `12% of AVGO purchases`, or `--` where the filing names the link without a figure. */
+export function hopLabel(hop: RippleHop) {
+  if (hop.pct == null) return "--";
+  return `${hop.pct}%${hop.scoped ? "*" : ""} of ${hop.owner}${hop.basis && hop.basis !== "revenue" ? ` ${hop.basis}` : ""}`;
+}
+
+export function projectSecondHop(chains: ReadonlyMap<string, SupplyChainPayload>, graphs: ReadonlyMap<string, GraphPayload>, reports: readonly EarningsCalendarReport[]): SecondHopRow[] {
+  const next = nextReports(reports);
+  const rows: SecondHopRow[] = [];
+  for (const { holding, company, via, link, path, graph } of secondHopLinks(chains, graphs)) {
+    const ticker = company.ticker!.toUpperCase();
+    const report = next.get(ticker);
+    if (!report) continue;
+    rows.push({ id: `${holding}:${link}:2:${ticker}`, company: ticker, companyName: report.name ?? company.name, link, date: report.date, timing: report.timing,
+      averageMove: report.averageReports >= MIN_AVERAGE_REPORTS ? report.averageMove : null, holding, holdingDate: next.get(holding.toUpperCase())?.date ?? null,
+      via: entityLabel(via), viaName: via.name, hops: [hopShare(graph, path.linkIds[0]!), hopShare(graph, path.linkIds[1]!)],
+      exposure: path.exposure ? exposureLabel(path, graph) : null });
+  }
+  return rows.sort((a, b) => a.date.localeCompare(b.date) || a.holding.localeCompare(b.holding) || a.company.localeCompare(b.company));
+}

package/src/plugins/builtin/earnings-ripple/pane.tsx

@@ -1,20 +1,25 @@
-import { useCallback, useMemo } from "react";
-import { DataTableView, EmptyState, PaneStatusBody, usePaneFooter, usePaneNoticeFooter,
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { DataTableView, EmptyState, PaneStatusBody, usePaneFooter, usePaneNoticeFooter, usePaneTabs,
   type DataTableCell, type DataTableColumn, type PaneHint } from "../../../components";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { getTableWidth } from "../../../components/ui/table-layout";
 import { usePlanAccess } from "../../../api-client/plan-access";
 import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState, useTickers } from "../../../public/react";
 import type { PaneProps } from "../../../types/plugin";
 import { Box } from "../../../ui";
 import { isUsListingExchange } from "../../../utils/exchanges";
+import { displayWidth } from "../../../utils/format";
 import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { UpgradeLabel } from "../shared/locked-rows";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
-import { cachedRippleSources, loadRipple } from "./client";
-import { revenueOwner, RIPPLE_DAYS, type RippleRow } from "./model";
+import { cachedRippleSources, loadRipple, rippleRouteSettings } from "./client";
+import { hopLabel, revenueOwner, RIPPLE_DAYS, type RippleRow, type SecondHopRow } from "./model";
 
-/** Calls per refresh stay bounded: one disclosure request per holding. */
+/** Calls per refresh stay bounded: one disclosure request per holding, plus one graph request per holding on the second hop. */
 const RIPPLE_HOLDINGS_LIMIT = 60;
 
+const TABS = [{ value: "direct", label: "1 hop" }, { value: "two-hop", label: "2 hops" }];
+
 const COLUMNS: DataTableColumn[] = [
   { id: "date", label: "Date", width: 11, align: "left" },
   { id: "timing", label: "Time", width: 5, align: "left" },
@@ -26,6 +31,67 @@ const COLUMNS: DataTableColumn[] = [
   { id: "holdingDate", label: "Holding reports", width: 16, align: "right" },
 ];
 
+const SECOND_HOP_COLUMNS: DataTableColumn[] = [
+  { id: "date", label: "Date", width: 10, align: "left" },
+  { id: "timing", label: "Time", width: 5, align: "left" },
+  { id: "company", label: "Reports", width: 14, flexGrow: 1, align: "left" },
+  { id: "link", label: "Link", width: 19, align: "left" },
+  { id: "via", label: "Via", width: 9, align: "left" },
+  { id: "holding", label: "Holding", width: 9, align: "left" },
+  { id: "shares", label: "Share per hop", width: 28, align: "left" },
+  { id: "move", label: "Avg move", width: 9, align: "right" },
+  { id: "holdingDate", label: "Holding reports", width: 16, align: "right" },
+];
+const HOP_SEPARATOR = " › ";
+
+/**
+ * Holding to via, then via to the company that reports. The first hop is
+ * padded with no-break spaces, which the desktop does not collapse.
+ */
+function shareText(row: SecondHopRow, firstHopWidth: number) {
+  const first = hopLabel(row.hops[0]);
+  return `${first}${"\u00a0".repeat(Math.max(0, firstHopWidth - displayWidth(first)))}${HOP_SEPARATOR}${hopLabel(row.hops[1])}`;
+}
+
+/**
+ * The 2 hops table at this width. The date, the company and the route (via,
+ * holding, every hop's share) always show, so the route never scrolls out of
+ * view; a pane too narrow for all of it clips the shares. What room is left
+ * goes to the rest, most needed first, each only if it fits: the link, the
+ * report time, a long via name in full, the average move, shares lined up so
+ * every second hop starts at the same place, and the holding's own report.
+ * `firstHopWidth` is what the first hop is padded to, 0 when not lined up.
+ */
+function secondHopLayout(width: number, rows: readonly SecondHopRow[]) {
+  const widest = (texts: readonly string[]) => Math.max(0, ...texts.map(displayWidth));
+  const firstHop = widest(rows.map((row) => hopLabel(row.hops[0])));
+  const shares = Math.min(44, Math.max(28, widest(rows.map((row) => shareText(row, 0)))));
+  const aligned = Math.min(44, Math.max(shares, firstHop + HOP_SEPARATOR.length + widest(rows.map((row) => hopLabel(row.hops[1])))));
+  const widths: Record<string, number> = { via: 9, shares };
+  let firstHopWidth = 0;
+  const shown = new Set(["date", "company", "via", "holding", "shares"]);
+  const columns = () => SECOND_HOP_COLUMNS.filter((column) => shown.has(column.id))
+    .map((column) => widths[column.id] ? { ...column, width: widths[column.id]! } : column);
+  // The vertical scrollbar takes a cell, including when the rows fit.
+  const room = () => width - 1 - getTableWidth(columns());
+  const fitted = widths.shares = Math.max(28, shares + Math.min(0, room()));
+  const extras: [add: () => void, undo: () => void][] = [
+    ...["link", "timing"].map((id): [() => void, () => void] => [() => shown.add(id), () => shown.delete(id)]),
+    [() => { widths.via = Math.min(18, Math.max(9, widest(rows.map((row) => row.via)))); }, () => { widths.via = 9; }],
+    [() => shown.add("move"), () => shown.delete("move")],
+    [() => { widths.shares = aligned; firstHopWidth = firstHop; }, () => { widths.shares = fitted; firstHopWidth = 0; }],
+    [() => shown.add("holdingDate"), () => shown.delete("holdingDate")],
+  ];
+  for (const [add, undo] of extras) {
+    add();
+    if (room() < 0) undo();
+  }
+  return { columns: columns(), firstHopWidth };
+}
+
+const move = (row: RippleRow | SecondHopRow): DataTableCell =>
+  ({ text: row.averageMove == null ? "--" : `±${(row.averageMove * 100).toFixed(1)}%`, value: row.averageMove });
+
 function renderCell(row: RippleRow, column: DataTableColumn): DataTableCell {
   switch (column.id) {
     case "date": return { text: row.date };
@@ -34,16 +100,34 @@ function renderCell(row: RippleRow, column: DataTableColumn): DataTableCell {
     case "link": return { text: row.link === "customer" ? "customer of" : "supplier to" };
     case "holding": return { text: row.holding };
     case "pct": return { text: `${row.pctOfRevenue}%${row.pctScope ? "*" : ""} of ${revenueOwner(row)}`, value: row.pctOfRevenue };
-    case "move": return { text: row.averageMove == null ? "--" : `±${(row.averageMove * 100).toFixed(1)}%`, value: row.averageMove };
+    case "move": return move(row);
+    default: return { text: row.holdingDate ?? "--" };
+  }
+}
+
+function renderSecondHopCell(row: SecondHopRow, column: DataTableColumn, firstHopWidth: number): DataTableCell {
+  switch (column.id) {
+    case "date": return { text: row.date };
+    case "timing": return { text: row.timing?.toUpperCase() ?? "--" };
+    case "company": return { text: `${row.company} ${row.companyName}` };
+    case "link": return { text: row.link === "customer" ? "customer's customer" : "supplier's supplier" };
+    case "via": return { text: row.via };
+    case "holding": return { text: row.holding };
+    case "shares": return { text: shareText(row, firstHopWidth), value: shareText(row, 0) };
+    case "move": return move(row);
     default: return { text: row.holdingDate ?? "--" };
   }
 }
 
 export function EarningsRipplePane({ width, height, focused }: PaneProps) {
   const [symbolsText] = usePaneSettingValue("symbols", "");
+  const [openingTab] = usePaneSettingValue("tab", "direct");
+  const [savedTab, setTab] = usePluginPaneState<string>("tab", openingTab);
+  const tab = savedTab === "two-hop" ? "two-hop" : "direct";
   const tickers = useTickers();
   const { createPaneFromTemplate } = usePluginAppActions();
   const [selectedId, setSelectedId] = usePluginPaneState<string | null>("selectedRow", null);
+  const [selectedSecondId, setSelectedSecondId] = usePluginPaneState<string | null>("selectedSecondHop", null);
   const session = useResearchCloudSession();
   const access = usePlanAccess();
   const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
@@ -58,46 +142,87 @@ export function EarningsRipplePane({ width, height, focused }: PaneProps) {
   }, [symbolsText, tickers]);
   const holdings = scope.holdings;
   const holdingsKey = holdings.join(",");
-  const loader = useCallback((force: boolean) => loadRipple(holdings, cachedRippleSources(accessKey, force)), [holdingsKey, accessKey]);
+  const secondHop = tab === "two-hop";
+  // A free account's graph stops at one hop, so it makes no graph requests and its second tab reuses the first load.
+  // Once a Pro account opens 2 hops the graph stays in the load, so going back and forth between tabs never reloads.
+  // A refresh on 1 hop reads the graphs from the cache instead of asking for them again.
+  const [graphOpened, setGraphOpened] = useState(false);
+  useEffect(() => { if (secondHop && access.hasProAccess) setGraphOpened(true); }, [secondHop, access.hasProAccess]);
+  const graphHop = access.hasProAccess && (secondHop || graphOpened);
+  const secondHopShown = useRef(secondHop);
+  secondHopShown.current = secondHop;
+  const loader = useCallback((force: boolean) => loadRipple(holdings,
+    cachedRippleSources(accessKey, force, !graphHop ? "off" : secondHopShown.current ? "load" : "cached"), undefined, { secondHop: graphHop }),
+  [holdingsKey, accessKey, graphHop]);
   const ripple = useAsyncResource(holdings.length ? loader : null);
   useAutoRefresh(ripple.updatedAt, ripple.load);
   usePaneRefreshKey(() => { void ripple.reload(); }, { focused });
+  const { strip, rows: tabRows } = usePaneTabs(holdings.length ? { tabs: TABS, activeValue: tab, onSelect: setTab, focused, dense: true } : null);
 
   const rows = ripple.data?.rows ?? [];
+  const second = secondHop ? ripple.data?.secondHop ?? null : null;
+  const secondRows = second?.rows ?? [];
   const selected = rows.find((row) => row.id === selectedId) ?? rows[0] ?? null;
+  const selectedSecond = secondRows.find((row) => row.id === selectedSecondId) ?? secondRows[0] ?? null;
+  const current = secondHop ? selectedSecond : selected;
   const failures = ripple.data?.failures ?? [];
   const truncated = ripple.data?.truncated ?? [];
+  const locked = secondHop && (!access.hasProAccess || !!second?.locked);
   const openUpgrade = useCloudUpgradeAction("ripl");
   usePaneNoticeFooter({ registrationId: "earnings-ripple-notices", focused, notices: [
     ...(scope.total > holdings.length ? [`Checking ${holdings.length} of ${scope.total} holdings${scope.named ? "" : ", positions first. Name tickers in pane settings to pick others"}`] : []),
     ...(failures.length ? [`No disclosures for ${failures.map((failure) => failure.symbol).join(", ")}`] : []),
-    ...(truncated.length ? [`Free preview: top three customers and suppliers for ${truncated.join(", ")}`] : []),
+    ...(!secondHop && truncated.length ? [`Free preview: top three customers and suppliers for ${truncated.join(", ")}`] : []),
+    ...(second?.failures.length ? [`No two-hop graph for ${second.failures.map((failure) => failure.symbol).join(", ")}`] : []),
+    // The graph returns at most 50 companies per direction, so a large holding's list can be cut short.
+    ...(second?.truncated.length ? [`Graph search capped for ${second.truncated.map((entry) => entry.symbol).join(", ")}; some companies two hops away may be missing`] : []),
   ] });
   const openSupply = useCallback((row: RippleRow) => createPaneFromTemplate("supply-chain-pane", { symbol: row.holding }), [createPaneFromTemplate]);
+  // SPLC's own table does not reach a company two hops away; its Path view shows the row's route.
+  const openRoute = useCallback((row: SecondHopRow) => createPaneFromTemplate("supply-chain-pane", { symbol: row.holding, values: rippleRouteSettings(row) }),
+    [createPaneFromTemplate]);
   usePaneFooter("earnings-ripple", () => {
     const hints: PaneHint[] = [
-      ...(selected ? [
-        { id: "supply", key: "s", label: "upply chain", onPress: () => openSupply(selected) },
-        { id: "earnings", key: "e", label: "arnings", onPress: () => createPaneFromTemplate("earnings-calendar-pane", { arg: selected.company }) },
-      ] : []),
-      ...(truncated.length ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: openUpgrade }] : []),
+      ...(secondHop && selectedSecond ? [{ id: "supply", key: "s", label: "upply chain", title: `Supply chain path from ${selectedSecond.holding} to ${selectedSecond.company}`,
+        onPress: () => openRoute(selectedSecond) }]
+        : !secondHop && selected ? [{ id: "supply", key: "s", label: "upply chain", onPress: () => openSupply(selected) }] : []),
+      ...(current ? [{ id: "earnings", key: "e", label: "arnings", onPress: () => createPaneFromTemplate("earnings-calendar-pane", { arg: current.company }) }] : []),
+      ...((secondHop ? locked : truncated.length) ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: openUpgrade }] : []),
     ];
     return { info: [
-      ...(ripple.loading ? [{ id: "loading", parts: [{ text: "loading disclosures", tone: "muted" as const }] }] : []),
+      ...(ripple.loading ? [{ id: "loading", parts: [{ text: secondHop && graphHop ? "loading supply chain graph" : "loading disclosures", tone: "muted" as const }] }] : []),
       ...(ripple.data?.stale ? [{ id: "stale", parts: [{ text: "stale", tone: "warning" as const }] }] : []),
     ], hints };
-  }, [ripple.loading, ripple.data?.stale, selected, openSupply, createPaneFromTemplate, truncated.length, openUpgrade]);
+  }, [ripple.loading, ripple.data?.stale, current, selected, selectedSecond, secondHop, graphHop, locked, openSupply, openRoute, createPaneFromTemplate, truncated.length, openUpgrade]);
 
+  const secondLayout = useMemo(() => secondHopLayout(width, secondRows), [width, secondRows]);
+  const firstHopWidth = secondLayout.firstHopWidth;
+  const renderSecondCell = useCallback((row: SecondHopRow, column: DataTableColumn) => renderSecondHopCell(row, column, firstHopWidth), [firstHopWidth]);
+  const windowMeta = () => [["window", `${ripple.data?.from} to ${ripple.data?.to}`]];
+  const bodyHeight = Math.max(3, height - tabRows);
   return <Box width={width} height={height} flexDirection="column" overflow="hidden">
+    {strip}
     {!holdings.length ? <EmptyState title="Add tickers to a portfolio or watchlist, or name them in pane settings." />
-      : <PaneStatusBody subject="earnings ripple" loading={ripple.loading && !ripple.data} error={!ripple.data ? ripple.error : null}
-        empty={!!ripple.data && !rows.length} emptyTitle={`No disclosed customer or supplier of these holdings reports in the next ${RIPPLE_DAYS} days.`}>
-        <DataTableView<RippleRow> focused={focused} columns={COLUMNS} items={rows} rootWidth={width} rootHeight={height}
-          getItemKey={(row) => row.id} emptyStateTitle="No reports." sortColumnId={null} sortDirection="asc"
-          selection={{ kind: "id", selectedId: selected?.id ?? null, getId: (row) => row.id, onChange: setSelectedId }}
-          onActivate={openSupply}
-          getExportMetadata={() => [["window", `${ripple.data?.from} to ${ripple.data?.to}`], ["revenue share", "percent of the seller's revenue, as its filing discloses"]]}
-          renderCell={renderCell} />
+      : secondHop && locked ? <Box paddingX={1} paddingTop={1}><EmptyState title="Companies two hops away need Gloom Pro."
+        actions={<UpgradeLabel text="Upgrade for two-hop supply chains" onPress={openUpgrade} role="ripple-upgrade" />} /></Box>
+      : <PaneStatusBody subject={secondHop ? "two-hop supply chains" : "earnings ripple"} loading={ripple.loading && (!ripple.data || (secondHop && !second))}
+        error={!ripple.data ? ripple.error : null}
+        empty={secondHop ? !!second && !secondRows.length : !!ripple.data && !rows.length}
+        emptyTitle={secondHop ? `No company two disclosed hops from these holdings reports in the next ${RIPPLE_DAYS} days.`
+          : `No disclosed customer or supplier of these holdings reports in the next ${RIPPLE_DAYS} days.`}>
+        {secondHop
+          ? <DataTableView<SecondHopRow> focused={focused} columns={secondLayout.columns} items={secondRows} rootWidth={width} rootHeight={bodyHeight}
+            getItemKey={(row) => row.id} emptyStateTitle="No reports." sortColumnId={null} sortDirection="asc"
+            selection={{ kind: "id", selectedId: selectedSecond?.id ?? null, getId: (row) => row.id, onChange: setSelectedSecondId }}
+            onActivate={openRoute}
+            getExportMetadata={() => [...windowMeta(), ["share per hop", "percent of the reporting company's revenue unless another basis is named, holding to via, then via to the company"]]}
+            renderCell={renderSecondCell} />
+          : <DataTableView<RippleRow> focused={focused} columns={COLUMNS} items={rows} rootWidth={width} rootHeight={bodyHeight}
+            getItemKey={(row) => row.id} emptyStateTitle="No reports." sortColumnId={null} sortDirection="asc"
+            selection={{ kind: "id", selectedId: selected?.id ?? null, getId: (row) => row.id, onChange: setSelectedId }}
+            onActivate={openSupply}
+            getExportMetadata={() => [...windowMeta(), ["revenue share", "percent of the seller's revenue, as its filing discloses"]]}
+            renderCell={renderCell} />}
       </PaneStatusBody>}
   </Box>;
 }

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

@@ -361,6 +361,7 @@ function EconCalendarPane({ focused, width, height }: PaneProps) {
 export const economicCalendarModule: PluginModule = {
   panes: [{
     id: "econ-calendar",
+    reportFreshness: { status: "not-a-feed", basis: "calendar" },
     name: "Economic Calendar",
     icon: "E",
     component: EconCalendarPane,

package/src/plugins/builtin/econ-statistics/headless.ts

@@ -123,6 +123,8 @@ export function projectStatsHeadlessBundle(
 
 export const econStatisticsHeadless: HeadlessPaneDefinition<"bundle"> = {
   shape: "bundle",
+  // Each row checks its own release schedule and says when it is stale.
+  freshness: { source: "FRED", status: "not-a-feed", basis: "published statistics" },
   argument: {
     kind: "free-text",
     placeholder: "statistic",