@gloom-sh/terminal 0.0.0-stage → 0.19.0

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

@@ -0,0 +1,229 @@
+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";
+import { freePreviewNote } from "../shared/free-preview";
+
+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(" · ");
+/** Labels that name a part of the company, shown before the basis and the qualifiers. */
+const PART_KEY = /segment|product|offering|business|brand|platform|market|geograph|region|division|cloud|franchise|program|channel|line|customer|entity|scope|type|category/;
+/** Labels that say how a figure is measured, shown after the basis. */
+const QUALIFIER_KEY = /exclud|includ|except|without|compar|dilution|window|funded|horizon/;
+const FLAG_VALUE = /^(?:true|yes|y)$/i;
+const FALSE_VALUE = /^(?:false|no|n)$/i;
+const EXCLUDED_VALUE = /^(?:excluded|excludes|excluding|exclusive|ex)$/i;
+const INCLUDED_VALUE = /^(?:included|includes|including|inclusive)$/i;
+const plain = (text: string) => text.replaceAll("_", " ").replace(/\s+/g, " ").trim();
+/** One label in plain words: "Data Center", "excl. fuel", "year over year", never its key. */
+function labelWords(key: string, value: string): string | null {
+  const said = plain(value);
+  const subject = plain(key).replace(/\b(?:excluded|excludes|excluding|exclude|without|included|includes|including|include|ex)\b/gi, " ").replace(/\s+/g, " ").trim();
+  if (!said || FALSE_VALUE.test(said)) return null;
+  if (EXCLUDED_VALUE.test(said) || (FLAG_VALUE.test(said) && /exclud|without|(?:^|_)ex(?:_|$)/i.test(key))) return subject ? `excl. ${subject}` : null;
+  if (INCLUDED_VALUE.test(said) || (FLAG_VALUE.test(said) && /includ/i.test(key))) return subject ? `incl. ${subject}` : null;
+  if (FLAG_VALUE.test(said)) return subject || null;
+  if (/^(?:exclud|except|without)/i.test(key) && !/^(?:excl|exclud|except|without|ex\b)/i.test(said)) return `excl. ${said}`;
+  if (/^includ/i.test(key) && !/^incl/i.test(said)) return `incl. ${said}`;
+  return said;
+}
+const labelRank = (key: string) => QUALIFIER_KEY.test(key) ? 2 : PART_KEY.test(key) ? 0 : 1;
+/** What a series' labels name, in plain words: its parts, then its qualifiers. Empty for the company's consolidated figure. */
+export function scopeWords(dimensions: Record<string, string>, which: "parts" | "qualifiers" | "all" = "all"): string {
+  return Object.entries(dimensions)
+    .filter(([key]) => which === "all" || (which === "qualifiers") === (labelRank(key) === 2))
+    .sort(([a], [b]) => labelRank(a) - labelRank(b) || a.localeCompare(b))
+    .map(([key, value]) => labelWords(key, value)).filter((words): words is string => !!words)
+    .filter((words, index, list) => list.indexOf(words) === index).join(" · ");
+}
+/** The labels that tell a row's series apart: the server's `seriesLabels`, else (a server before them) its stored labels. */
+export const seriesLabels = (row: Pick<CompanyRow, "dimensions" | "seriesLabels">) => row.seriesLabels ?? row.dimensions;
+/**
+ * What tells a series apart from the metric's other series, in plain words:
+ * its parts, a basis other than reported, then its qualifiers.
+ * "Data Center", "Adjusted · diluted", "International · Constant currency".
+ */
+export function seriesDetail(row: Pick<CompanyRow, "basis" | "dimensions" | "seriesLabels">): string {
+  const labels = seriesLabels(row);
+  return [scopeWords(labels, "parts"), row.basis === "reported" ? "" : basisLabel(row.basis), scopeWords(labels, "qualifiers")].filter(Boolean).join(" · ");
+}
+/** A series named in plain words: "Revenue · Data Center", for a chart's series list and a detail title. */
+export const seriesName = (row: Pick<CompanyRow, "metric" | "basis" | "dimensions" | "seriesLabels">) => [row.metric.name, seriesDetail(row)].filter(Boolean).join(" · ");
+const KIND_ORDER = ["quarter", "half", "ytd", "year", "instant", "other"];
+const BASIS_ORDER = ["reported", "adjusted", "constant_currency", "organic"];
+/** Series in reading order: by metric, the consolidated figure before its parts, reported before other bases, a quarter before its year. */
+export function seriesOrder(a: CompanyRow, b: CompanyRow): number {
+  const rank = (list: string[], value: string) => { const index = list.indexOf(value); return index < 0 ? list.length : index; };
+  const parts = (row: CompanyRow) => scopeWords(seriesLabels(row), "parts");
+  return a.metric.name.localeCompare(b.metric.name) || Number(parts(a) !== "") - Number(parts(b) !== "") || parts(a).localeCompare(parts(b))
+    || rank(BASIS_ORDER, a.basis) - rank(BASIS_ORDER, b.basis) || scopeWords(seriesLabels(a), "qualifiers").localeCompare(scopeWords(seriesLabels(b), "qualifiers"))
+    || rank(KIND_ORDER, a.period.kind) - rank(KIND_ORDER, b.period.kind);
+}
+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. */
+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: Pick<CompanyRow, "period">) => 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;
+}
+/** Columns that say nothing while every row is the company's consolidated, as-reported figure. */
+export const QUIET_COLUMNS = { basis: ["Reported"], scope: ["Consolidated"] };
+/** The text of a table cell as the pane draws it; the report prints the same words. */
+export function companyCellText(row: CompanyRow, column: string, observations: KpiObservation[]): string {
+  const guide = isGuidance(row) ? row : null;
+  if (column === "change") return guide ? directionLabel(guide.direction) : changeText(observationChange(row as KpiObservation, observations));
+  return column === "metric" ? row.metric.name : column === "period" ? fiscalLabel(row) : column === "value" ? `${guide ? rangeText(guide) : observationValue(row as KpiObservation)}${guide?.status === "withdrawn" || guide?.hedge === "qualitative" ? "" : unitSuffix(row)}`
+    : column === "unit" ? unitLabel(row)
+    : column === "basis" ? basisLabel(row.basis) : column === "scope" ? dimensionLabel(row.dimensions) || "Consolidated"
+    : column === "issued" ? guide?.issuedDate ?? "--" : column === "actual" ? guide?.actual ? `${valueText(row, guide.actual.value)}${unitSuffix(row)}` : "--"
+    : column === "outcome" ? guide ? outcomeLabel(guide) : "--" : column === "published" ? row.evidence[0]!.publishedAt.slice(0, 10)
+    : column === "confidence" ? `${Math.round(row.confidence * 100)}%` : column === "revision" ? `${row.revision} ${row.current ? "current" : "superseded"}` : row.evidence[0]!.quote;
+}
+/**
+ * The table's columns. `named` is the desktop's: the metric cell names the
+ * series in plain words (seriesDetail), so no basis or scope column repeats it.
+ */
+export function companyColumns(guidance: boolean, evidence: boolean, history: boolean, trend = false, named = 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;
+  const shown = named ? columns.filter((column) => column.id !== "basis" && column.id !== "scope") : columns;
+  return order ? shown.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id)) : shown;
+}
+
+/** What a missing KPI means, as KPIS states it among its limitations and EQS beside a KPI column with gaps. */
+export const KPI_COVERAGE_NOTE = "Coverage follows available company disclosures; missing data is not zero.";
+
+/**
+ * Why Free shows no value of a metric, in the same words in `fn KPIS`, `fn GUIDE` and EQS: "Order backlog is not
+ * among the 3 free KPI values; Gloom Pro shows all 63." With no free value at all, `where` says which free view
+ * shows none; without a total (EQS counts no company's disclosures), Pro shows each company's metric.
+ */
+export function kpiFreeLimitNote({ metric, shown, total, guidance = false, where = "The free preview" }: {
+  /** The metric's name: "Order backlog", "Backlog". */
+  metric: string;
+  /** How many values Free shows. */
+  shown: number;
+  /** How many Gloom Pro shows, when the response says. */
+  total: number | null;
+  guidance?: boolean;
+  where?: string;
+}): string {
+  const count = (value: number) => value.toLocaleString("en-US");
+  const noun = (value: number) => `${guidance ? "guidance figure" : "KPI value"}${value === 1 ? "" : "s"}`;
+  const pro = total == null ? `Gloom Pro shows each company's ${metric}` : `Gloom Pro shows all ${count(total)}`;
+  return shown === 0 ? `${where} shows no ${noun(0)}; ${pro}.`
+    : `${metric} is not ${shown === 1 ? "the" : "among the"} ${count(shown)} free ${noun(shown)}; ${pro}.`;
+}
+
+/** The lock line of a free preview, in the same words in the pane and `fn KPIS` / `fn GUIDE`. */
+export function companyPreviewNote(data: Pick<KpisPayload, "lockedRows" | "totalRows" | "coverage">, guidance: boolean): string {
+  const count = (value: number) => value.toLocaleString("en-US");
+  const rows = `${count(data.totalRows)} ${guidance ? "guidance figures" : "KPI values"}`;
+  return freePreviewNote({ shows: data.lockedRows > 0 ? `${count(Math.max(0, data.totalRows - data.lockedRows))} of ${rows}` : rows,
+    adds: data.lockedRows > 0 ? `the other ${count(data.lockedRows)}` : null, historyFrom: data.coverage.firstPeriod });
+}

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

@@ -0,0 +1,256 @@
+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 { listingAbroad } from "../../../api-client/paths";
+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 { quoteBlockStyle } from "../../../components/ui/quote";
+import { ClippedText } from "../../../components/ui/display";
+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 { useOpenDescription } from "../shared/open-description";
+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, companyCellText, companyColumns, dimensionLabel, directionLabel, directionTone, guideGroupKey, guidanceSeries, fiscalLabel,
+  isGuidance, exactObservation, observationValue, observationChange, observationChart, periodOrder, outcomeLabel, QUIET_COLUMNS, rangeText, scopeWords, seriesDetail, seriesLabel, seriesLabels, seriesName,
+  seriesOrder, unitLabel, valueText, companyPreviewNote, type CompanyRow } from "./model";
+import { PriceSparkline } from "../../../components/price-sparkline/view";
+import type { PricePoint } from "../../../types/financials";
+import { toneColor, withoutQuietColumns } from "../shared/research-cells";
+
+/** A locked placeholder, or with `note` the line above them saying what free shows and what Pro adds. */
+type Item = { id: string; row: CompanyRow } | { id: string; row: null; note?: string };
+const getId = (item: Item) => item.id;
+const isNote = (item: Item) => "note" in item && !!item.note;
+function DisclosureEvidence({ row, sourceId, onSource, width }: { row: CompanyRow; sourceId: string | null; onSource: (id: string) => void; width: number }) {
+  const colors = useThemeColors();
+  const desktop = useUiCapabilities().nativePaneChrome === true;
+  const evidence = row.evidence.find((entry) => entry.id === sourceId) ?? row.evidence[0]!;
+  // The desktop's detail body already holds the pane's inset.
+  return <Box flexDirection="column" paddingX={desktop ? 0 : 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={(desktop ? scopeWords(seriesLabels(row)) : 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} />
+      {/* The filing's own words: on the desktop, the quote block. */}
+      {desktop
+        ? <Box marginY={1} style={quoteBlockStyle()}><Text fg={colors.textBright} wrapText>{evidence.quote}</Text></Box>
+        : <Box paddingY={1}><Text fg={colors.textBright}>{evidence.quote}</Text></Box>}
+      <Text fg={colors.textDim}>{evidence.url}</Text>
+    </Box>
+  </Box>;
+}
+
+/** The pane's ticker, with the venue and company a listing abroad is asked about by. */
+function useCompanyListing() {
+  const { symbol, ticker } = usePaneTickerIdentity();
+  const abroad = symbol ? listingAbroad(symbol, ticker?.metadata.exchange, ticker?.metadata.name) : null;
+  return { symbol, exchange: abroad?.exchange, name: abroad?.name, key: JSON.stringify([symbol, abroad?.exchange, abroad?.name]) };
+}
+export function CompanyKpisPane(props: PaneProps) {
+  const { key, ...listing } = useCompanyListing();
+  return <CompanyView key={`${key}:kpis`} {...props} {...listing} mode="kpis" />;
+}
+export function CompanyGuidancePane(props: PaneProps) {
+  const { key, ...listing } = useCompanyListing();
+  return <CompanyView key={`${key}:guidance`} {...props} {...listing} mode="guidance" />;
+}
+function CompanyView({ symbol, exchange, name, mode, width, height, focused }: PaneProps & { symbol: string | null; exchange?: string; name?: string; mode: CompanyMode }) {
+  const colors = useThemeColors();
+  const host = useRendererHost();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const openDescription = useOpenDescription();
+  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, { exchange, name }), [mode, symbol, exchange, name, accessKey, snapshot]);
+  const resource = useAsyncResource(symbol ? loader : null, { initialData: () => symbol ? cachedCompanyData(mode, symbol, accessKey, { exchange, name }) : 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", ...(mode === "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);
+  // The desktop lists KPIs by metric, each series named in plain words; the terminal keeps its frames.
+  const [sort, setSort] = usePluginPaneState<{ column: string; direction: "asc" | "desc" }>("company:sort",
+    desktop && mode === "kpis" ? { column: "metric", direction: "asc" } : { 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: `${desktop ? seriesName(row) : seriesLabel(row)} · ${row.period.kind}` }])).values()]
+    : [...new Map(eligible.filter(isGuidance).map((row) => [guideGroupKey(row), { value: guideGroupKey(row), label: `${desktop ? seriesName(row) : seriesLabel(row)} · ${row.period.label}` }])).values()], [eligible, mode, desktop]);
+  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);
+    };
+    const direction = sort.direction === "asc" ? 1 : -1;
+    if (desktop && sort.column === "metric") return [...values].sort((a, b) => (seriesOrder(a, b) || periodOrder(b).localeCompare(periodOrder(a)) || a.id.localeCompare(b.id)) * direction);
+    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)) * direction;
+    });
+  }, [eligible, tab, activePlot, guidance, kpis, sort, observations, desktop]);
+  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 previewNote = preview ? companyPreviewNote(data, mode === "guidance") : null;
+  const items = useMemo<Item[]>(() => [...rows.map((row) => ({ id: row.id, row })), ...(previewNote ? [{ id: "note:preview", row: null, note: previewNote }] : []),
+    ...Array.from({ length: lockedCount }, (_, index) => ({ id: `locked:${index}`, row: null }))], [rows, lockedCount, previewNote]);
+  // 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, desktop),
+    rows, (row, id) => id === "basis" ? basisLabel(row.basis) : id === "scope" ? dimensionLabel(row.dimensions) || "Consolidated" : "", QUIET_COLUMNS), [mode, tab, trends, rows, width, desktop]);
+  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 signInWall = !data && isCloudSessionRequired(resource.error);
+  const { strip, rows: tabRows } = usePaneTabs(symbol && !signInWall ? { 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: () => openDescription(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, openDescription]);
+  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 (signInWall) return <SignInWall placement="company-kpis-signin" action={mode === "guidance" ? "view company guidance" : "view company KPIs"} 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], _index: number, state: { selected: boolean }): DataTableCell => {
+    const row = item.row;
+    if (!row) {
+      if (isNote(item)) return { text: "" };
+      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) };
+    }
+    if (desktop && column.id === "metric") {
+      // The series in plain words: the metric bright, what tells it apart dim. The detail starts from no width and takes
+      // what the name leaves, so it gives way first and the name is cut only when it alone does not fit.
+      const detail = seriesDetail(row);
+      return { text: detail ? `${row.metric.name}  ${detail}` : row.metric.name, content: <Box flexDirection="row" height={1} overflow="hidden" flexShrink={1} minWidth={0}>
+        <ClippedText fg={state.selected ? colors.selectedText : colors.textBright} text={row.metric.name} width={column.width} />
+        {detail ? <ClippedText fg={state.selected ? colors.selectedText : colors.textDim} lead="  " text={detail} width={column.width} flex="1 1 0%" /> : null}
+      </Box> };
+    }
+    const text = companyCellText(row, column.id, observations);
+    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) : isNote(item) ? undefined : openUpgrade()} renderCell={renderCell}
+        isNavigable={(item) => !isNote(item)} renderSectionHeader={(item) => "note" in item && item.note ? { text: item.note } : null} freezeFirstColumn selectedTextOverridesCellColor showHorizontalScrollbar
+        detailOpen={!!openRow} onBack={() => setOpen(null)} detailTitle={openRow ? `${desktop ? seriesName(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,51 @@
+import { apiClient } from "../../../api-client";
+import type { PaneScreenshotEvidenceHook } from "../../../cli/pane-functions/screenshot-evidence";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { isRecord } from "../../../utils/guards";
+import { resolveIssuerListing } from "../shared/headless-market-data";
+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, context }) {
+      const symbol = resolved.createOptions?.symbol ?? resolved.createOptions?.arg;
+      if (!symbol) throw new Error("A company disclosure screenshot requires a ticker");
+      // A bare symbol takes the saved listing's venue, as the pane does.
+      const saved = parsePublicTickerKey(symbol).exchange ? null : await context.store.loadTicker(symbol).catch(() => null);
+      const listing = await resolveIssuerListing(symbol, saved?.metadata.exchange, context.dataProvider);
+      const payload = await fetchCompanyData(mode, symbol, companyQuery(resolved.options), apiClient, listing);
+      // Keyed by the requested ticker: a listing abroad is answered under its bare symbol.
+      return { settings: { companySnapshot: payload }, financials: [[symbol.trim().toUpperCase(), { 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");