gloomberb 0.15.7 → 0.16.0

package/src/plugins/builtin/company-kpis/model.ts

@@ -0,0 +1,124 @@
+import type { GuidancePayload, KpiGuidance, KpiObservation, KpiSeries, KpiUnit, KpisPayload } from "../../../api-client/company-kpis";
+import type { DataTableColumn } from "../../../components";
+import { scalarPoint, staticSeries } from "../../../components/chart/static/series";
+import type { CompositeChartXAxis } from "../../../components/chart/composite/types";
+import { formatCompact, formatNumber } from "../../../utils/format";
+
+export type CompanyRow = KpiObservation | KpiGuidance;
+export const isGuidance = (row: CompanyRow): row is KpiGuidance => "issuedDate" in row;
+export const basisLabel = (basis: string) => ({ reported: "Reported", adjusted: "Adjusted", constant_currency: "Constant currency", organic: "Organic" })[basis] ?? basis;
+export const dimensionLabel = (dimensions: Record<string, string>) => Object.entries(dimensions).sort(([a], [b]) => {
+  const rank = (key: string) => ["segment", "product", "geography", "region", "cohort"].includes(key) ? 0 : key === "comparison" ? 2 : 1;
+  return rank(a) - rank(b) || a.localeCompare(b);
+}).map(([key, value]) => `${key.replaceAll("_", " ")}: ${value.replaceAll("_", " ")}`).join(" · ");
+export const unitLabel = (row: Pick<CompanyRow, "unit" | "currency" | "dimensions">) => ({
+  currency: row.currency ?? "Currency", currency_per_share: `${row.currency ?? "Currency"}/share`, currency_per_unit: `${row.currency ?? "Currency"}/${row.dimensions.unit ?? "unit"}`,
+  percent: "%", basis_points: "bp", count: "Count", ratio: "x", volume: row.dimensions.unit ?? "Volume",
+})[row.unit];
+function numberText(value: number | null | undefined, unit: KpiUnit, withUnit = true): string {
+  if (value == null) return "--";
+  const number = Math.abs(value) >= 10_000 ? formatCompact(value, { fixedDecimals: true }) : formatNumber(value, Number.isInteger(value) ? 0 : 2);
+  return `${number}${!withUnit ? "" : unit === "percent" ? "%" : unit === "basis_points" ? "bp" : unit === "ratio" ? "x" : ""}`;
+}
+export const exactObservation = (row: KpiObservation) => !row.valueQualifier || row.valueQualifier === "exact";
+export const observationValue = (row: KpiObservation, withUnit = true) => `${({ exact: "", approximately: "≈ ", at_least: "≥ ", at_most: "≤ ", greater_than: "> ", less_than: "< " })[row.valueQualifier ?? "exact"]}${numberText(row.value, row.unit, withUnit)}`;
+export const valueText = (row: CompanyRow, value: number | null, withUnit = true) => numberText(value, row.unit, withUnit);
+export const rangeText = (row: KpiGuidance, withUnit = true) => row.status === "withdrawn" ? "Withdrawn" : row.hedge === "qualitative" ? row.rangeText
+  : row.point !== null ? `${({ approximately: "≈ ", at_least: "≥ ", at_most: "≤ ", greater_than: "> ", less_than: "< " } as Record<string, string>)[row.hedge] ?? ""}${valueText(row, row.point, withUnit)}`
+  : row.low !== null && row.high !== null ? `${row.hedge === "approximately" ? "≈ " : ""}${valueText(row, row.low, withUnit)} – ${valueText(row, row.high, withUnit)}`
+  : row.low !== null ? `${row.hedge === "greater_than" ? ">" : "≥"} ${valueText(row, row.low, withUnit)}`
+  : row.high !== null ? `${row.hedge === "less_than" ? "<" : "≤"} ${valueText(row, row.high, withUnit)}` : row.rangeText;
+/** The unit a value cell carries after its number; percent, bp and x are already in the number. */
+export function unitSuffix(row: Pick<CompanyRow, "unit" | "currency" | "dimensions">): string {
+  if (row.unit === "currency") return row.currency ? ` ${row.currency}` : "";
+  if (row.unit === "currency_per_share") return ` ${row.currency ?? ""}/sh`.replace(" /", " ");
+  if (row.unit === "currency_per_unit" || row.unit === "volume") return ` ${unitLabel(row)}`;
+  return "";
+}
+/** Raised reads as good news, a cut as bad, a reiteration as no news. */
+export const directionTone = (direction: KpiGuidance["direction"]) => direction === "raised" ? "positive" as const : direction === "cut" ? "negative" as const
+  : direction === "withdrawn" ? "warning" as const : direction === "initiated" ? "text" as const : "muted" as const;
+/** A change is good when it moves the way the metric's owner wants it to. */
+export const changeTone = (row: KpiObservation, value: number | null) => value === null || value === 0 || row.metric.favorable === "neutral" ? "muted" as const
+  : (value > 0) === (row.metric.favorable === "higher") ? "positive" as const : "negative" as const;
+export const directionLabel = (direction: KpiGuidance["direction"]) => direction === "not_comparable" ? "Not comparable" : direction.charAt(0).toUpperCase() + direction.slice(1);
+export const outcomeLabel = (row: KpiGuidance) => !row.actual ? "Pending" : row.actual.favorable === "in_line" ? "In range"
+  : row.actual.favorable === "neutral" ? row.actual.outcome === "above" ? "Above" : row.actual.outcome === "below" ? "Below" : "In range"
+  : row.actual.favorable === "beat" ? "Beat" : "Miss";
+export const seriesLabel = (series: Pick<KpiSeries, "metric" | "basis" | "dimensions" | "unit" | "currency">) =>
+  `${series.metric.name} · ${basisLabel(series.basis)} · ${unitLabel(series)}${Object.keys(series.dimensions).length ? ` · ${dimensionLabel(series.dimensions)}` : ""}`;
+export const guideGroupKey = (row: KpiGuidance) => JSON.stringify([row.seriesKey, row.period.start, row.period.end, row.period.kind, row.period.fiscalYear, row.period.fiscalQuarter, row.period.end === null && (row.period.fiscalYear === null || row.period.kind !== "year" && row.period.fiscalQuarter === null) ? row.period.label.toLocaleLowerCase() : null]);
+export function allObservations(data: KpisPayload): KpiObservation[] {
+  return [...new Map([...data.series.flatMap((series) => series.observations), ...data.revisions].map((row) => [row.id, row])).values()];
+}
+export function allGuidance(data: GuidancePayload): KpiGuidance[] {
+  return [...new Map([...data.guidance, ...data.history].map((row) => [row.id, row])).values()];
+}
+export function observationChange(row: KpiObservation, observations: KpiObservation[]): { value: number | null; unit: string } {
+  const fiscalOrder = (item: KpiObservation) => item.period.fiscalYear !== null && (item.period.kind === "year" || item.period.fiscalQuarter !== null)
+    ? item.period.fiscalYear * 4 + (item.period.fiscalQuarter ?? 0) : null;
+  const previousPeriod = (other: KpiObservation) => other.period.end && row.period.end ? other.period.end < row.period.end
+    : fiscalOrder(other) !== null && fiscalOrder(row) !== null && fiscalOrder(other)! < fiscalOrder(row)!;
+  const prior = observations.filter((other) => other.id !== row.id && other.current && !other.conflict && !other.contested && exactObservation(other) && other.seriesKey === row.seriesKey
+    && other.period.kind === row.period.kind && previousPeriod(other)).sort((a, b) => periodOrder(b).localeCompare(periodOrder(a)))[0];
+  if (!prior || (row.conflict || row.contested) || !exactObservation(row)) return { value: null, unit: "" };
+  if (row.unit === "percent") return { value: row.value - prior.value, unit: "pp" };
+  if (row.unit === "basis_points") return { value: row.value - prior.value, unit: "bp" };
+  if (prior.value === 0) return { value: null, unit: "%" };
+  return { value: (row.value - prior.value) / Math.abs(prior.value) * 100, unit: "%" };
+}
+export const changeText = (change: { value: number | null; unit: string }) => change.value === null ? "--" : `${change.value > 0 ? "+" : ""}${formatNumber(change.value, 2)}${change.unit}`;
+export const fiscalLabel = (row: CompanyRow) => row.period.fiscalYear === null ? row.period.label
+  : row.period.kind === "year" ? `FY${row.period.fiscalYear}`
+  : row.period.fiscalQuarter !== null ? `Q${row.period.fiscalQuarter} FY${row.period.fiscalYear}${row.period.kind === "ytd" ? " YTD" : ""}` : row.period.label;
+export const periodOrder = (row: CompanyRow) => row.period.fiscalYear !== null
+  ? `${row.period.fiscalYear}:${row.period.fiscalQuarter ?? 0}:${row.period.end ?? ""}` : row.period.end ?? row.period.label;
+export function observationChart(rows: KpiObservation[], color: string) {
+  const valid = rows.filter((row) => row.current && !row.conflict && !row.contested && exactObservation(row));
+  const categorical = valid.some((row) => !row.period.end);
+  const values = valid.filter((row) => !categorical || row.period.fiscalYear !== null && (row.period.kind === "year" || row.period.fiscalQuarter !== null))
+    .sort((a, b) => periodOrder(a).localeCompare(periodOrder(b)));
+  const dates = new Map<string, Date>();
+  // These are positions in the plotting API, never calendar dates: both axis and cursor
+  // are replaced with fiscal labels, and the captured/source observation retains end:null.
+  values.forEach((row, index) => dates.set(row.id, categorical ? new Date(index * 30 * 86_400_000) : new Date(row.period.end!)));
+  const first = values[0];
+  const compatible = first && values.every((row) => row.seriesKey === first.seriesKey && row.period.kind === first.period.kind);
+  const series = values.length >= 2 && compatible ? [staticSeries(values.map((row) => scalarPoint(dates.get(row.id)!, row.value)),
+    { id: `${first.seriesKey}:${first.period.kind}`, label: `${first.metric.name} (${first.period.kind})`, color, calendarSpaced: true })] : [];
+  const xAxis: CompositeChartXAxis | undefined = categorical ? {
+    ticks: values.map((row, index) => ({ ratio: index / Math.max(1, values.length - 1), label: fiscalLabel(row) })),
+    formatCursor: (ratio) => values[Math.max(0, Math.min(values.length - 1, Math.round(ratio * (values.length - 1))))] ? fiscalLabel(values[Math.max(0, Math.min(values.length - 1, Math.round(ratio * (values.length - 1))))]!) : "",
+  } : undefined;
+  return { series, dates, xAxis, ...(categorical && first ? { viewport: { start: dates.get(first.id)!, end: dates.get(values.at(-1)!.id)! } } : {}) };
+}
+export function guidanceSeries(rows: KpiGuidance[], selected: KpiGuidance | undefined, colors: { low: string; high: string; actual: string }) {
+  if (!selected) return [];
+  const compatible = rows.filter((row) => guideGroupKey(row) === guideGroupKey(selected) && row.status === "active")
+    .sort((a, b) => a.issuedDate.localeCompare(b.issuedDate) || a.asOf.localeCompare(b.asOf));
+  const timeline = [...new Map(compatible.map((row) => [row.issuedDate, row])).values()];
+  if (timeline.length < 2) return [];
+  const spec = [{ id: "low", label: "Guide low", color: colors.low }, { id: "high", label: "Guide high", color: colors.high }, { id: "point", label: "Point guide", color: colors.high }] as const;
+  const series = spec.flatMap((field) => timeline.filter((row) => row[field.id] !== null).length < 2 ? [] : [staticSeries(timeline.map((row) => scalarPoint(new Date(row.issuedDate), row[field.id])), { ...field, calendarSpaced: true })]);
+  const actual = selected.actual;
+  if (actual && series.length) series.push(staticSeries(timeline.map((row) => scalarPoint(new Date(row.issuedDate), actual.value)), { id: "actual", label: "Later actual", color: colors.actual, calendarSpaced: true }));
+  return series;
+}
+export function companyColumns(guidance: boolean, evidence: boolean, history: boolean, trend = false): DataTableColumn[] {
+  const columns: DataTableColumn[] = [
+    { id: "metric", label: "Metric", width: 27, flexGrow: 1, align: "left" },
+    { id: "period", label: "Fiscal period", width: 14, align: "left" },
+    { id: "value", label: guidance ? "Guide" : "Value", width: guidance ? 26 : 16, align: "right" },
+    { id: "change", label: guidance ? "Action" : "Prior change", width: 13, align: "right" },
+    ...(trend ? [{ id: "trend", label: "Trend", width: 16, align: "left" as const }] : []),
+    ...(guidance ? [{ id: "issued", label: "Issued", width: 11, align: "left" as const },
+      ...(history ? [{ id: "actual", label: "Actual", width: 16, align: "right" as const }, { id: "outcome", label: "Outcome", width: 10, align: "left" as const }] : [])] : []),
+    { id: "basis", label: "Basis", width: 18, align: "left" },
+    { id: "scope", label: "Scope", width: 24, align: "left" },
+    ...(evidence ? [{ id: "published", label: "Published", width: 11, align: "left" as const }, { id: "confidence", label: "Confidence", width: 11, align: "right" as const },
+      { id: "revision", label: "Revision", width: 12, align: "left" as const }, { id: "quote", label: "Evidence", width: 54, align: "left" as const }] : []),
+  ];
+  const order = evidence ? ["metric", "period", "quote", "published", "confidence", "revision", "value", "basis", "scope", "issued", "change"]
+    : history ? ["metric", "period", "actual", "outcome", "value", "issued", "change", "basis", "scope"] : null;
+  return order ? columns.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id)) : columns;
+}

package/src/plugins/builtin/company-kpis/pane.tsx

@@ -0,0 +1,226 @@
+import { useCallback, useMemo, useRef } from "react";
+import { isAccessDenied } from "../../../api-client/errors";
+import { usePlanAccess } from "../../../api-client/plan-access";
+import type { KpiObservation } from "../../../api-client/company-kpis";
+import { ChartTableHeader, DataTableStackView, DetailScrollBody, EmptyState, KeyValueRow, PaneStatusBody, QueryBar, SectionHeading,
+  useChartTableSelection, usePaneMenuItems, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, type DataTableCell, type PaneHint } from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import { usePaneTickerIdentity } from "../../../state/hooks/pane-ticker";
+import { useThemeColors } from "../../../theme/theme-context";
+import type { PaneProps } from "../../../types/plugin";
+import { Box, Text, useRendererHost, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
+import { SignInWall } from "../cloud/auth-actions";
+import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { Blurred, LockedOverlay, UpgradeLabel } from "../shared/locked-rows";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { cachedCompanyData, loadCompanyData, KPI_UNAVAILABLE, validateCompanyData, type CompanyDataset, type CompanyMode } from "./client";
+import { useCompanyEvidence } from "./screenshot-evidence";
+import { allGuidance, allObservations, basisLabel, changeText, changeTone, companyColumns, dimensionLabel, directionLabel, directionTone, guideGroupKey, guidanceSeries, fiscalLabel,
+  isGuidance, exactObservation, observationValue, observationChange, observationChart, periodOrder, outcomeLabel, rangeText, seriesLabel, unitLabel, unitSuffix, valueText, type CompanyRow } from "./model";
+import { PriceSparkline } from "../../../components/price-sparkline/view";
+import type { PricePoint } from "../../../types/financials";
+import { toneColor, withoutQuietColumns } from "../shared/research-cells";
+
+/** Columns that say nothing while every row is the company's consolidated, as-reported figure. */
+const QUIET_COLUMNS = { basis: ["Reported"], scope: ["Consolidated"] };
+
+type Item = { id: string; row: CompanyRow } | { id: string; row: null };
+const getId = (item: Item) => item.id;
+function DisclosureEvidence({ row, sourceId, onSource, width }: { row: CompanyRow; sourceId: string | null; onSource: (id: string) => void; width: number }) {
+  const colors = useThemeColors();
+  const evidence = row.evidence.find((entry) => entry.id === sourceId) ?? row.evidence[0]!;
+  return <Box flexDirection="column" paddingX={1}>
+    {row.evidence.length > 1 ? <QueryBar width={Math.max(1, width - 4)} filters={[{ id: "source", label: "Document", value: evidence.id,
+      options: row.evidence.map((entry) => ({ value: entry.id, label: `${entry.publishedAt.slice(0, 10)} · ${entry.title}` })), onChange: onSource }]} /> : null}
+    <KeyValueRow label="Value" value={isGuidance(row) ? rangeText(row) : observationValue(row)} detail={row.currency || row.unit === "volume" || row.unit === "count" ? unitLabel(row) : undefined} labelWidth={18} />
+    <KeyValueRow label="Fiscal period" value={row.period.label} detail={row.period.end ? row.period.start ? `${row.period.start} to ${row.period.end}` : `${row.period.kind === "instant" ? "As of" : "Ended"} ${row.period.end}` : "Calendar dates unavailable"} labelWidth={18} />
+    <KeyValueRow label="Basis" value={basisLabel(row.basis)} labelWidth={18} />
+    <KeyValueRow label="Scope" value={dimensionLabel(row.dimensions) || "Consolidated"} labelWidth={18} />
+    <KeyValueRow label="Definition" value={row.metric.definition} labelWidth={18} />
+    <KeyValueRow label="Revision" value={`${row.revision}${row.current ? " · current" : " · superseded"}${!isGuidance(row) && (row.conflict || row.contested) ? " · conflicting disclosures" : ""}`} labelWidth={18} />
+    {row.revisionReason ? <KeyValueRow label="Correction" value={row.revisionReason} labelWidth={18} /> : null}
+    {isGuidance(row) ? <>
+      <KeyValueRow label="Issued" value={row.issuedDate} detail={directionLabel(row.direction)} labelWidth={18} />
+      <KeyValueRow label="Source range" value={row.rangeText} labelWidth={18} />
+      {row.conditions ? <KeyValueRow label="Conditions" value={row.conditions} labelWidth={18} /> : null}
+      <KeyValueRow label="Later actual" value={row.actual ? valueText(row, row.actual.value) : "Pending"} detail={row.actual ? outcomeLabel(row) : undefined} labelWidth={18} />
+    </> : null}
+    <Box key={evidence.id} flexDirection="column" paddingTop={1}>
+      <SectionHeading title="Source evidence" />
+      <KeyValueRow label="Document" value={evidence.title} labelWidth={18} />
+      <KeyValueRow label="Published" value={evidence.publishedAt.slice(0, 10)} detail={`${evidence.country} · ${evidence.language}`} labelWidth={18} />
+      <KeyValueRow label="Confidence" value={`${Math.round(evidence.confidence * 100)}%`} detail={evidence.quoteMatchMode === "exact" ? "Exact text match" : "Normalized text match"} labelWidth={18} />
+      <Box paddingY={1}><Text fg={colors.textBright}>{evidence.quote}</Text></Box>
+      <Text fg={colors.textDim}>{evidence.url}</Text>
+    </Box>
+  </Box>;
+}
+
+export function CompanyKpisPane(props: PaneProps) {
+  const { symbol } = usePaneTickerIdentity();
+  return <CompanyView key={`${symbol}:kpis`} {...props} symbol={symbol} mode="kpis" />;
+}
+export function CompanyGuidancePane(props: PaneProps) {
+  const { symbol } = usePaneTickerIdentity();
+  return <CompanyView key={`${symbol}:guidance`} {...props} symbol={symbol} mode="guidance" />;
+}
+function CompanyView({ symbol, mode, width, height, focused }: PaneProps & { symbol: string | null; mode: CompanyMode }) {
+  const colors = useThemeColors();
+  const host = useRendererHost();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const session = useResearchCloudSession();
+  const access = usePlanAccess();
+  const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
+  const openUpgrade = useCloudUpgradeAction(mode === "kpis" ? "kpis" : "guide");
+  const [snapshotSetting] = usePaneSettingValue<CompanyDataset | null>("companySnapshot", null);
+  const snapshot = useMemo(() => { try { return snapshotSetting ? validateCompanyData(snapshotSetting) : null; } catch { return null; } }, [snapshotSetting]);
+  const loader = useCallback((force: boolean) => snapshot ? Promise.resolve({ payload: snapshot, stale: false, refreshError: null }) : loadCompanyData(mode, symbol!, accessKey, force), [mode, symbol, accessKey, snapshot]);
+  const resource = useAsyncResource(symbol ? loader : null, { initialData: () => symbol ? cachedCompanyData(mode, symbol, accessKey) : null, clearOnError: isAccessDenied });
+  const data = resource.data?.payload;
+  const kpis = data && "series" in data ? data : null;
+  const guidance = data && "guidance" in data ? data : null;
+  const [openingTab] = usePaneSettingValue("tab", "table");
+  const [tabValue, setTab] = usePluginPaneState<string>("company:tab", openingTab);
+  const tab = ["table", "chart", "evidence", ...(guidance ? ["history"] : [])].includes(tabValue) ? tabValue : "table";
+  const [openingMetric] = usePaneSettingValue("metric", "all");
+  const [metric, setMetric] = usePluginPaneState<string>("company:metric", openingMetric);
+  const [plotKey, setPlotKey] = usePluginPaneState<string>("company:plot", "");
+  const [selectedId, setSelected] = usePluginPaneState<string | null>(`company:selected:${tab}`, null);
+  const [openId, setOpen] = usePluginPaneState<string | null>("company:open", null);
+  const [sourceId, setSource] = usePluginPaneState<string | null>("company:source", null);
+  const [sort, setSort] = usePluginPaneState<{ column: string; direction: "asc" | "desc" }>("company:sort", { column: "period", direction: "desc" });
+  const detailScrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const observations = useMemo(() => kpis ? allObservations(kpis) : [], [kpis]);
+  const guides = useMemo(() => guidance ? allGuidance(guidance) : [], [guidance]);
+  const allRows = useMemo<CompanyRow[]>(() => [...observations, ...guides], [observations, guides]);
+  const eligible = useMemo(() => allRows.filter((row) => metric === "all" || row.metricId === metric), [allRows, metric]);
+  const plotOptions = useMemo(() => mode === "kpis"
+    ? [...new Map(eligible.filter((row) => !isGuidance(row)).map((row) => [`${row.seriesKey}:${row.period.kind}`, { value: `${row.seriesKey}:${row.period.kind}`, label: `${seriesLabel(row)} · ${row.period.kind}` }])).values()]
+    : [...new Map(eligible.filter(isGuidance).map((row) => [guideGroupKey(row), { value: guideGroupKey(row), label: `${seriesLabel(row)} · ${row.period.label}` }])).values()], [eligible, mode]);
+  const activePlot = plotOptions.some((option) => option.value === plotKey) ? plotKey : plotOptions[0]?.value ?? "";
+  const rows = useMemo(() => {
+    const values = eligible.filter((row) => tab === "chart" ? (isGuidance(row) ? guideGroupKey(row) : `${row.seriesKey}:${row.period.kind}`) === activePlot
+      : tab === "history" ? isGuidance(row) && !!row.actual
+      : tab === "evidence" ? true : isGuidance(row) ? guidance?.guidance.some((current) => current.id === row.id) : kpis?.series.some((series) => series.latest.id === row.id));
+    const key = (row: CompanyRow): string | number | null => {
+      const guide = isGuidance(row) ? row : null;
+      return sort.column === "metric" ? row.metric.name : sort.column === "value" ? guide ? guide.point ?? guide.low ?? guide.high : (row as KpiObservation).value
+        : sort.column === "issued" ? guide?.issuedDate ?? null : sort.column === "confidence" ? row.confidence
+        : sort.column === "actual" ? guide?.actual?.value ?? null : sort.column === "outcome" ? guide ? outcomeLabel(guide) : null
+        : sort.column === "basis" ? row.basis : sort.column === "unit" ? unitLabel(row) : sort.column === "scope" ? dimensionLabel(row.dimensions)
+        : sort.column === "published" ? row.evidence[0]!.publishedAt : sort.column === "revision" ? row.revision
+        : sort.column === "quote" ? row.evidence[0]!.quote : sort.column === "change" ? guide ? guide.direction : observationChange(row as KpiObservation, observations).value
+        : periodOrder(row);
+    };
+    return [...values].sort((a, b) => { const x = key(a), y = key(b);
+      return x === null || y === null ? x === y ? a.id.localeCompare(b.id) : x === null ? 1 : -1
+        : (x < y ? -1 : x > y ? 1 : a.metric.name.localeCompare(b.metric.name) || dimensionLabel(a.dimensions).localeCompare(dimensionLabel(b.dimensions)) || a.id.localeCompare(b.id)) * (sort.direction === "asc" ? 1 : -1);
+    });
+  }, [eligible, tab, activePlot, guidance, kpis, sort, observations]);
+  const selected = rows.find((row) => row.id === selectedId) ?? rows[0];
+  const openRow = allRows.find((row) => row.id === openId);
+  const activeRow = openRow ?? selected;
+  const preview = data?.access === "preview" && data.lockedRows > 0;
+  const lockedCount = preview ? Math.min(3, data.lockedRows) : 0;
+  const items = useMemo<Item[]>(() => [...rows.map((row) => ({ id: row.id, row })), ...Array.from({ length: lockedCount }, (_, index) => ({ id: `locked:${index}`, row: null }))], [rows, lockedCount]);
+  // One trend per series beside its latest value, once a series has three comparable points.
+  const trends = useMemo(() => {
+    const map = new Map<string, PricePoint[]>();
+    for (const series of kpis?.series ?? []) {
+      const points = series.observations.filter((row) => row.current && !row.conflict && !row.contested && exactObservation(row) && row.period.end && row.period.kind === series.latest.period.kind)
+        .sort((a, b) => periodOrder(a).localeCompare(periodOrder(b))).map((row) => ({ date: new Date(row.period.end!), close: row.value }));
+      if (points.length >= 3) map.set(series.latest.id, points);
+    }
+    return map;
+  }, [kpis]);
+  const columns = useMemo(() => withoutQuietColumns(companyColumns(mode === "guidance", tab === "evidence", tab === "history", mode === "kpis" && tab === "table" && trends.size > 0 && width >= 100),
+    rows, (row, id) => id === "basis" ? basisLabel(row.basis) : id === "scope" ? dimensionLabel(row.dimensions) || "Consolidated" : "", QUIET_COLUMNS), [mode, tab, trends, rows, width]);
+  const metricOptions = useMemo(() => [{ value: "all", label: "All metrics" }, ...[...new Map(allRows.map((row) => [row.metricId, { value: row.metricId, label: row.metric.name }])).values()]], [allRows]);
+  const kpiChart = useMemo(() => observationChart(rows.filter((row): row is KpiObservation => !isGuidance(row)), colors.warning), [rows, colors.warning]);
+  const series = useMemo(() => tab !== "chart" ? [] : mode === "kpis" ? kpiChart.series
+    : guidanceSeries(guides, selected && isGuidance(selected) ? selected : undefined, { low: colors.textMuted, high: colors.warning, actual: colors.positive }), [tab, mode, kpiChart, guides, selected, colors]);
+  const link = useChartTableSelection({ rows, getId: (row) => row.id, getDate: (row) => isGuidance(row) ? new Date(row.issuedDate) : kpiChart.dates.get(row.id) ?? null,
+    selectedId: selected?.id ?? null, onSelect: setSelected, focused: focused && !openRow, enabled: tab === "chart" });
+  const { strip, rows: tabRows } = usePaneTabs(data ? { tabs: [{ value: "table", label: mode === "guidance" ? "Tracker" : "Table" }, { value: "chart", label: "Chart" },
+    ...(mode === "guidance" ? [{ value: "history", label: "History" }] : []), { value: "evidence", label: "Evidence" }], activeValue: tab,
+    onSelect: (value) => { setTab(value); setOpen(null); }, focused, dense: true } : null);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  usePaneRefreshKey(() => void resource.reload(), { focused });
+  useCompanyEvidence(data ?? null, mode, tab, rows.map((row) => row.id));
+  const hints: PaneHint[] = [
+    ...(activeRow ? [{ id: "evidence", key: "e", label: "vidence", onPress: () => setOpen(activeRow.id) },
+      { id: "source", key: "o", label: "pen source", onPress: () => void host.openExternal((activeRow.evidence.find((entry) => entry.id === sourceId) ?? activeRow.evidence[0]!).url) }] : []),
+    ...(symbol ? [{ id: "related", key: "c", label: mode === "kpis" ? "ompany guidance" : "ompany KPIs", onPress: () => createPaneFromTemplate(mode === "kpis" ? "company-guidance-pane" : "company-kpis-pane", { symbol }) },
+    ] : []),
+    ...(preview ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: openUpgrade }] : []),
+  ];
+  usePaneMenuItems("company-disclosures:research", () => symbol ? [
+    { id: "description", label: "Description (DES)", onSelect: () => createPaneFromTemplate("new-ticker-detail-pane", { symbol }) },
+    { id: "financials", label: "Financial Analysis (FA)", onSelect: () => createPaneFromTemplate("financial-analysis-pane", { symbol }) },
+    { id: "price-chart", label: "Price Chart (G)", onSelect: () => createPaneFromTemplate("chart-composer-pane", { arg: symbol }) },
+  ] : null, [symbol, createPaneFromTemplate]);
+  usePaneStatusFooter({ registrationId: "company-kpis", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale,
+    info: data?.asOf ? [{ id: "as-of", parts: [{ text: `as of ${data.asOf.slice(0, 10)}`, tone: "muted" as const }] }] : [], hints });
+  usePaneNoticeFooter({ registrationId: "company-kpis:notices", focused, notices: [resource.data?.refreshError,
+    data?.truncated && data.access === "full" ? "The response reached its stored-record limit. Narrow the metric or date range in a CLI or REST query." : null,
+    data?.coverage.conflicts ? "Conflicting disclosures are retained in Evidence and excluded from comparable trends." : null].filter((value): value is string => !!value) });
+  if (!symbol) return <EmptyState title="Select a ticker." />;
+  if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement="company-kpis-signin" action="view company KPIs and guidance" needsVerification={session.needsVerification} />;
+  const bodyHeight = Math.max(3, height - tabRows);
+  const query = <QueryBar width={width} filters={[{ id: "metric", label: "Metric", value: metric, defaultValue: "all", options: metricOptions,
+    onChange: (value: string) => { setMetric(value); setSelected(null); setOpen(null); } }, ...(tab === "chart" && plotOptions.length ? [{ id: "series", label: "Series", value: activePlot,
+      options: plotOptions, onChange: (value: string) => { setPlotKey(value); setSelected(null); } }] : [])]} />;
+  const renderCell = (item: Item, column: (typeof columns)[number]): DataTableCell => {
+    const row = item.row;
+    if (!row) {
+      if (!desktop && column.id === "metric" && item.id === "locked:0") return { text: "Unlock with Pro", content: <UpgradeLabel text="Unlock with Pro" onPress={openUpgrade} />, onMouseDown: openUpgrade };
+      return desktop ? { text: "", content: <Blurred><Text fg={colors.textDim}>{column.id === "metric" ? "Additional disclosure" : "Hidden"}</Text></Blurred> } : { text: "░░░░░", color: colors.textDim };
+    }
+    const guide = isGuidance(row) ? row : null;
+    if (column.id === "trend") {
+      const points = trends.get(row.id);
+      if (!points) return { text: "" };
+      const change = observationChange(row as KpiObservation, observations).value;
+      const tone = changeTone(row as KpiObservation, change);
+      return { text: "", content: <PriceSparkline priceHistory={points} width={column.width} period="all" trend={tone === "muted" ? "neutral" : tone} /> };
+    }
+    if (column.id === "change") {
+      if (guide) return { text: directionLabel(guide.direction), color: toneColor(directionTone(guide.direction), colors), keepColorWhenSelected: guide.direction === "raised" || guide.direction === "cut" };
+      const change = observationChange(row as KpiObservation, observations);
+      return { text: changeText(change), value: change.value, color: toneColor(changeTone(row as KpiObservation, change.value), colors) };
+    }
+    const text = column.id === "metric" ? row.metric.name : column.id === "period" ? fiscalLabel(row) : column.id === "value" ? `${guide ? rangeText(guide) : observationValue(row as KpiObservation)}${guide?.status === "withdrawn" || guide?.hedge === "qualitative" ? "" : unitSuffix(row)}`
+      : column.id === "unit" ? unitLabel(row)
+      : column.id === "basis" ? basisLabel(row.basis) : column.id === "scope" ? dimensionLabel(row.dimensions) || "Consolidated"
+      : column.id === "issued" ? guide?.issuedDate ?? "--" : column.id === "actual" ? guide?.actual ? `${valueText(row, guide.actual.value)}${unitSuffix(row)}` : "--"
+      : column.id === "outcome" ? guide ? outcomeLabel(guide) : "--" : column.id === "published" ? row.evidence[0]!.publishedAt.slice(0, 10)
+      : column.id === "confidence" ? `${Math.round(row.confidence * 100)}%` : column.id === "revision" ? `${row.revision} ${row.current ? "current" : "superseded"}` : row.evidence[0]!.quote;
+    return { text, ...(column.id === "value" && !guide ? { value: exactObservation(row as KpiObservation) ? (row as KpiObservation).value : observationValue(row as KpiObservation) } : column.id === "actual" ? { value: guide?.actual?.value } : {}),
+      color: column.id === "metric" ? colors.textBright : column.id === "value" || column.id === "actual" ? colors.textBright
+        : column.id === "outcome" && guide?.actual ? guide.actual.favorable === "beat" ? colors.positive : guide.actual.favorable === "miss" ? colors.negative : colors.text
+        : column.id === "period" || column.id === "basis" || column.id === "scope" || column.id === "issued" || column.id === "published" || column.id === "revision" || column.id === "confidence" ? colors.textDim : colors.text,
+      keepColorWhenSelected: column.id === "outcome" && (guide?.actual?.favorable === "beat" || guide?.actual?.favorable === "miss") };
+  };
+  return <Box width={width} height={height} flexDirection="column">
+    {strip}
+    <PaneStatusBody loading={!data && resource.loading} error={!data && resource.error !== KPI_UNAVAILABLE ? resource.error : null}
+      empty={!data && resource.error === KPI_UNAVAILABLE} emptyTitle={KPI_UNAVAILABLE} subject="company disclosures">
+      {data ? <DataTableStackView<Item> focused={focused} rootWidth={width} rootHeight={bodyHeight} columns={columns} items={items} getItemKey={getId}
+        selection={{ kind: "id", selectedId: selected?.id ?? null, getId, onChange: setSelected }}
+        onActivate={(item) => item.row ? setOpen(item.row.id) : openUpgrade()} renderCell={renderCell} freezeFirstColumn selectedTextOverridesCellColor showHorizontalScrollbar
+        detailOpen={!!openRow} onBack={() => setOpen(null)} detailTitle={openRow ? `${openRow.metric.name} · ${fiscalLabel(openRow)}` : undefined}
+        detailScrollRef={detailScrollRef} detailContent={openRow ? <DetailScrollBody ref={detailScrollRef} resetScrollKey={openRow.id}><DisclosureEvidence row={openRow} sourceId={sourceId} onSource={setSource} width={width} /></DetailScrollBody> : null}
+        sortColumnId={sort.column} sortDirection={sort.direction} onHeaderClick={(column) => setSort((previous) => ({ column, direction: previous.column === column && previous.direction === "desc" ? "asc" : "desc" }))}
+        resetScrollKey={`${mode}:${symbol}:${tab}:${metric}:${activePlot}`}
+        emptyStateTitle={tab === "history" ? "Actuals have not been matched to these guidance periods yet." : "No disclosed observations for this selection yet."}
+        rootBefore={<ChartTableHeader width={width} height={bodyHeight} tableRows={items.length} tableColumns={columns} query={query}
+          chart={tab === "chart" ? { series, ...(mode === "kpis" ? { xAxis: kpiChart.xAxis, viewport: kpiChart.viewport } : {}), empty: preview ? "Full history is available with Pro." : "History is accumulating. Two comparable disclosures are needed for a trend.",
+            formatValue: (value) => selected ? `${valueText(selected, value)}${selected.currency ? ` ${unitLabel(selected)}` : ""}` : String(value),
+            formatAxisValue: (value) => selected ? valueText(selected, value) : String(value), remoteKind: "company-disclosure-history", ...link } : null} />}
+        bodyAfter={lockedCount && desktop ? <LockedOverlay rows={lockedCount} text="Upgrade for all disclosures and history" onPress={openUpgrade} /> : undefined}
+      /> : null}
+    </PaneStatusBody>
+  </Box>;
+}

package/src/plugins/builtin/company-kpis/related.ts

@@ -0,0 +1,11 @@
+import { usePaneMenuItems } from "../../../components";
+import { usePluginAppActions } from "../../../public/react";
+
+/** Existing estimates and reported earnings stay in place; their menu opens cited company disclosures. */
+export function useCompanyDisclosureLinks(symbol: string | null) {
+  const { createPaneFromTemplate } = usePluginAppActions();
+  usePaneMenuItems("company-disclosures:related", () => symbol ? [
+    { id: "company-kpis", label: "Company KPIs (KPIS)", onSelect: () => createPaneFromTemplate("company-kpis-pane", { symbol }) },
+    { id: "company-guidance", label: "Company Guidance (GUIDE)", onSelect: () => createPaneFromTemplate("company-guidance-pane", { symbol }) },
+  ] : null, [symbol, createPaneFromTemplate]);
+}

package/src/plugins/builtin/company-kpis/screenshot-evidence.ts

@@ -0,0 +1,44 @@
+import type { PaneScreenshotEvidenceHook } from "../../../cli/pane-functions/screenshot-evidence";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import { isRecord } from "../../../utils/guards";
+import { companyQuery, fetchCompanyData, validateCompanyData, type CompanyDataset, type CompanyMode } from "./client";
+import { allGuidance, allObservations } from "./model";
+
+interface Evidence { kind: "company-disclosures"; version: 1; complete: boolean; plottedValueCount: number; payload: CompanyDataset; mode: CompanyMode; tab: string; rowIds: string[]; }
+export function useCompanyEvidence(payload: CompanyDataset | null, mode: CompanyMode, tab: string, rowIds: string[]) {
+  useRemoteUiNode({ role: "chart-data", label: "Rendered company disclosures", getMetadata: () => ({
+    kind: "company-disclosures", version: 1, complete: !!payload, ready: !!payload, plottedValueCount: rowIds.length, payload, mode, tab, rowIds,
+  }) });
+}
+function screenshotEvidence(mode: CompanyMode): PaneScreenshotEvidenceHook<Evidence> {
+  return {
+    paneId: mode === "kpis" ? "company-kpis" : "company-guidance", kind: "company-disclosures", label: "company disclosures",
+    async prepare({ resolved }) {
+      const symbol = resolved.createOptions?.symbol ?? resolved.createOptions?.arg;
+      if (!symbol) throw new Error("A company disclosure screenshot requires a ticker");
+      const payload = await fetchCompanyData(mode, symbol, companyQuery(resolved.options));
+      return { settings: { companySnapshot: payload }, financials: [[payload.symbol, { annualStatements: [], quarterlyStatements: [], priceHistory: [] }]] };
+    },
+    read(value) {
+      if (!isRecord(value) || value.kind !== "company-disclosures" || value.version !== 1 || value.mode !== mode || !isRecord(value.payload)
+        || !["table", "chart", "history", "evidence"].includes(String(value.tab)) || !Array.isArray(value.rowIds) || !value.rowIds.every((id) => typeof id === "string") || value.complete !== true) return null;
+      try {
+        const payload = validateCompanyData(value.payload as unknown as CompanyDataset);
+        const rows = "series" in payload ? allObservations(payload) : allGuidance(payload);
+        if (value.plottedValueCount !== value.rowIds.length || value.rowIds.some((id) => !rows.some((row) => row.id === id))) return null;
+        return value as unknown as Evidence;
+      } catch { return null; }
+    },
+    mismatches(evidence, { resolved, payload }) {
+      const snapshot = payload.config.layout.instances.find((entry) => entry.instanceId === payload.paneId)?.settings?.companySnapshot;
+      const issues: string[] = [];
+      if (JSON.stringify(evidence.payload) !== JSON.stringify(snapshot)) issues.push("Company disclosures differ from the captured source data");
+      if (evidence.tab !== (resolved.options.tab ?? "table")) issues.push("Company disclosure tab does not match");
+      return issues;
+    },
+    unavailable: (evidence) => evidence?.complete ? [] : ["company disclosures"],
+    symbols: ({ payload }) => payload.financials.map(([symbol]) => symbol),
+  };
+}
+export const companyKpisScreenshotEvidence = screenshotEvidence("kpis");
+export const companyGuidanceScreenshotEvidence = screenshotEvidence("guidance");

package/src/plugins/builtin/composite-plugins.ts

@@ -1,3 +1,13 @@
+import { creditDocumentsModule } from "./credit-documents";
+import { attentionModule } from "./attention";
+import { companyAttentionModule } from "./company-attention";
+import { catalystsModule } from "./catalysts";
+import { companyKpisModule } from "./company-kpis";
+import { powerModule } from "./power";
+import { perpsModule } from "./perps";
+import { exposureModule } from "./exposure";
+import { supplyChainModule } from "./supply-chain";
+import { awardsModule } from "./awards";
 import { cryptoBoardModule } from "./crypto-board";
 import { portfolioAnalyticsModule } from "./analytics";
 import { brokerManagerModule } from "./broker-manager";
@@ -12,12 +22,15 @@ import { creditBoardsModule } from "./credit-boards";
 import { creditConditionsModule } from "./credit-conditions";
 import { marketValuationModule } from "./market-valuation";
 import { economicCalendarModule } from "./econ";
+import { cpiModule } from "./cpi";
 import { econStatisticsModule } from "./econ-statistics";
 import { earningsModule } from "./earnings";
 import { earningsCallsModule } from "./earnings-calls";
 import { futuresModule } from "./futures";
 import { futuresCurveModule } from "./futures-curve";
 import { cotModule } from "./cot";
+import { doeModule } from "./doe";
+import { gpuModule } from "./gpu";
 import { fxMatrixModule } from "./fx-matrix";
 import { helpModule } from "./help";
 import { positionSizerModule } from "./kelly-sizer";
@@ -58,6 +71,10 @@ import { optionsCalculatorModule } from "./options-calculator";
 import { volSurfaceModule } from "./vol-surface";
 import { realizedVolModule } from "./realized-vol";
 import { seasonalityModule } from "./seasonality";
+import { earningsRippleModule } from "./earnings-ripple";
+import { reverseDcfModule } from "./reverse-dcf";
+import { peBandModule } from "./pe-band";
+import { macroDayModule } from "./macro-day";
 import { ivHistoryModule } from "./iv-history";
 import { backtestModule } from "./backtest";
 import { researchModule } from "./research";
@@ -98,6 +115,10 @@ export const tickerResearchPlugin = composeBuiltinPlugin({
     volSurfaceModule,
     realizedVolModule,
     seasonalityModule,
+    earningsRippleModule,
+    reverseDcfModule,
+    peBandModule,
+    macroDayModule,
     ivHistoryModule,
     backtestModule,
     estimateRevisionsModule,
@@ -106,6 +127,13 @@ export const tickerResearchPlugin = composeBuiltinPlugin({
     socialMentionsModule,
     debtMaturitiesModule,
     revenueBreakdownModule,
+    supplyChainModule,
+    creditDocumentsModule,
+    companyAttentionModule,
+    catalystsModule,
+    companyKpisModule,
+    awardsModule,
+    exposureModule,
     mnaModule,
     dividendYieldModule,
     holdersModule,
@@ -146,7 +174,12 @@ export const marketOverviewPlugin = composeBuiltinPlugin({
     futuresModule,
     futuresCurveModule,
     cotModule,
+    doeModule,
+    gpuModule,
+    attentionModule,
+    powerModule,
     cryptoBoardModule,
+    perpsModule,
   ],
 });
 
@@ -157,6 +190,7 @@ export const macroPlugin = composeBuiltinPlugin({
     macroSharedResourcesModule,
     economicCalendarModule,
     econStatisticsModule,
+    cpiModule,
     yieldCurveModule,
     ratePathModule,
     moneyMarketsModule,

package/src/plugins/builtin/correlation/history.ts

@@ -1,14 +1,17 @@
 import type { AssetDataProvider, MarketDataRequestContext } from "../../../types/data-provider";
 import type { TimeRange } from "../../../time-series/range";
+import type { ManualChartResolution } from "../../../time-series/resolution";
 import { clipPriceHistoryToRange } from "../../../time-series/history-window";
 
 /** Risk views need daily closes even when a chart preset defaults to intraday or weekly bars. */
+export const CORRELATION_HISTORY_RESOLUTION: ManualChartResolution = "1d";
+
 export async function loadCorrelationHistory(
   provider: AssetDataProvider, symbol: string, exchange: string, range: TimeRange,
   context?: MarketDataRequestContext,
 ) {
   const points = provider.getPriceHistoryForResolution
-    ? await provider.getPriceHistoryForResolution(symbol, exchange, range, "1d", context)
+    ? await provider.getPriceHistoryForResolution(symbol, exchange, range, CORRELATION_HISTORY_RESOLUTION, context)
     : await provider.getPriceHistory(symbol, exchange, range, context);
   return clipPriceHistoryToRange(points, range);
 }