gloomberb 0.15.7 → 0.16.0

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

@@ -0,0 +1,129 @@
+import type { DataTableColumn, StatItem } from "../../../components";
+import { scalarPoint, staticSeries } from "../../../components/chart/static/series";
+import type { HiringBoard, HiringPayload, HiringSummary } from "../../../api-client/hiring";
+import type { AppAttentionPayload, AppCompany } from "../../../api-client/app-attention";
+import { humanLabel } from "../shared/research-cells";
+
+export type AttentionKind = "hiring" | "apps";
+export type AttentionTab = "table" | "chart" | "mix" | "peers" | "evidence";
+export interface AttentionRow {
+  id: string;
+  values: Record<string, string | number | null>;
+  symbol?: string;
+  date?: string;
+  url?: string | null;
+  details?: Array<{ label: string; value: string }>;
+  app?: AppFocus;
+}
+export interface AppFocus { store: "app-store" | "google-play"; appId: string; name: string; country: string; chart: "free" | "paid" | "grossing" | "unranked" }
+interface AttentionSection {
+  columns: DataTableColumn[];
+  rows: AttentionRow[];
+  empty: string;
+}
+export interface AttentionModel {
+  asOf: string | null;
+  preview: boolean;
+  locked: number;
+  notices: string[];
+  figures: StatItem[];
+  sections: Record<AttentionTab, AttentionSection>;
+  chart: { label: string; unit: string; points: Array<{ date: string; value: number | null }> };
+}
+export const count = (value: number | null | undefined) => value == null ? "--" : value.toLocaleString("en-US", { maximumFractionDigits: 0 });
+const signed = (value: number | null | undefined, decimals = 0) => value == null ? "--" : `${value > 0 ? "+" : ""}${value.toLocaleString("en-US", { maximumFractionDigits: decimals })}`;
+const percent = (value: number | null | undefined) => value == null ? "--" : `${(value * 100).toFixed(1)}%`;
+const column = (id: string, label: string, width: number, numeric = false, flex = false): DataTableColumn => ({ id, label, width, align: numeric ? "right" : "left", ...(flex ? { flexGrow: 1 } : {}) });
+const roleFamily = (value: string | null) => value === "data_ai" || value === "data ai" ? "Data / AI" : value ? humanLabel(value) : null;
+const COMPANY_COLUMNS = [column("symbol", "Ticker", 12), column("name", "Company", 24, false, true), column("open", "Open roles", 12, true), column("net", "Net / week", 12, true), column("remote", "Remote %", 10, true), column("z", "Z-score", 10, true), column("signal", "Signal", 12), column("date", "As of", 12)];
+const HISTORY_COLUMNS = [column("date", "Week", 12), column("open", "Open roles", 12, true), column("added", "Added", 9, true), column("removed", "Removed", 9, true), column("net", "Net", 9, true), column("change", "Change %", 11, true), column("remote", "Remote %", 10, true), column("coverage", "Capture", 13, false, true)];
+const companyRow = (row: HiringSummary): AttentionRow => ({ id: row.symbol, symbol: row.symbol, values: { symbol: row.symbol, name: row.name, open: row.latest?.openCount ?? null, net: row.latest?.netChange ?? null, remote: row.latest?.remoteShare == null ? null : row.latest.remoteShare * 100, z: row.zScore, signal: humanLabel(row.signal ?? row.status), date: row.latest?.observedAt.slice(0, 10) ?? null } });
+
+export function hiringModel(data: HiringBoard | HiringPayload, mix = "functions"): AttentionModel {
+  const detail = "series" in data ? data : null;
+  const companies = "companies" in data ? data.companies : [data];
+  const history = detail?.series ?? [];
+  const latest = detail?.latest;
+  const mixKey = ["functions", "seniority", "countries", "locations", "signals"].includes(mix) ? mix as "functions" | "seniority" | "countries" | "locations" | "signals" : "functions";
+  const rows = mixKey === "signals" ? (detail?.signals ?? []).map((row, i): AttentionRow => ({ id: `${row.type}:${i}`, url: row.evidenceUrls[0], values: { label: row.label, count: row.value, share: row.confidence * 100, date: row.asOf.slice(0, 10) }, details: [{ label: "Observed", value: row.asOf }, { label: "Confidence", value: percent(row.confidence) }, { label: "Location", value: row.location ?? "--" }] }))
+    : (detail?.[mixKey] ?? []).map((row): AttentionRow => ({ id: row.id, values: { label: mixKey === "functions" ? roleFamily(row.label) : mixKey === "seniority" ? humanLabel(row.label) : row.label, count: row.count, share: row.share * 100 } }));
+  const model: AttentionModel = {
+    asOf: latest?.observedAt ?? data.generatedAt,
+    preview: data.preview,
+    locked: typeof data.locked === "number" ? data.locked : Object.values(data.locked).reduce((a, b) => a + b, 0),
+    // How counts compare is methodology (docs/hiring-app-attention.md); the footer keeps only what is wrong with this capture.
+    notices: detail ? [...(latest?.completeness !== "complete" ? ["The latest capture has incomplete or unknown coverage."] : []), ...(detail.status === "stale" ? ["The latest hiring capture is stale."] : [])] : [],
+    // A figure the first capture cannot give yet (a weekly change, a z-score) is left out, not shown as a dash.
+    figures: latest ? [
+      { label: "Open roles", value: count(latest.openCount) },
+      ...(latest.netChange != null ? [{ label: "Net / week", value: signed(latest.netChange), tone: latest.netChange === 0 ? "muted" as const : latest.netChange > 0 ? "positive" as const : "negative" as const }] : []),
+      ...(latest.remoteShare != null ? [{ label: "Remote", value: percent(latest.remoteShare), detail: "known work modes" }] : []),
+      ...(detail?.zScore != null ? [{ label: "Z-score", value: detail.zScore.toFixed(2), detail: detail.signal ? `hiring ${detail.signal}` : undefined,
+        tone: detail.signal === "surge" ? "positive" as const : detail.signal === "freeze" ? "negative" as const : undefined }] : []),
+    ] : [],
+    sections: {
+      table: { columns: COMPANY_COLUMNS, rows: companies.map(companyRow), empty: "Hiring observations are not available yet." },
+      chart: { columns: HISTORY_COLUMNS, rows: [...history].reverse().map((row): AttentionRow => ({ id: row.week, date: row.week, values: { date: row.week, open: row.openCount, added: row.added, removed: row.removed, net: row.netChange, change: row.changePct, remote: row.remoteShare == null ? null : row.remoteShare * 100, coverage: row.completeness }, details: [{ label: "Observed", value: row.observedAt }, { label: "Confidence", value: percent(row.confidence) }, { label: "Capture", value: row.kind }, { label: "Evergreen roles", value: count(row.evergreenCount) }] })), empty: data.preview ? "Full hiring history requires Pro." : "History is accumulating from the first capture." },
+      mix: { columns: [column("label", mixKey === "signals" ? "Signal" : "Group", 28, false, true), column("count", mixKey === "signals" ? "Value" : "Roles", 12, true), column("share", mixKey === "signals" ? "Confidence %" : "Share %", mixKey === "signals" ? 14 : 30, true), ...(mixKey === "signals" ? [column("date", "Observed", 12)] : [])], rows, empty: "No classified observations for this group yet." },
+      peers: { columns: COMPANY_COLUMNS, rows: (detail?.peers ?? []).map(companyRow), empty: "No comparable mapped peers yet." },
+      evidence: { columns: [column("title", "Role", 32, false, true), column("location", "Location", 24), column("function", "Function", 18), column("seniority", "Seniority", 13), column("date", "Observed", 12), column("confidence", "Confidence %", 13, true)], rows: (detail?.evidence ?? []).map((row): AttentionRow => ({ id: `${row.snapshotId}:${row.id}`, url: row.url ?? row.sourceUrl, values: { title: row.title, location: row.location, function: roleFamily(row.jobFunction), seniority: row.seniority ? humanLabel(row.seniority) : null, date: row.observedAt.slice(0, 10), confidence: row.confidence * 100 }, details: [{ label: "Posting title", value: row.title }, { label: "Location", value: row.location ?? "--" }, { label: "Country", value: row.country ?? "Unknown" }, { label: "Function", value: row.jobFunction ?? "Unclassified" }, { label: "Seniority", value: row.seniority ?? "Unclassified" }, { label: "Remote", value: row.remote === null ? "Unknown" : row.remote ? "Yes" : "No" }, { label: "Observed", value: row.observedAt }, { label: "Revision", value: String(row.revision) }, { label: "Confidence", value: percent(row.confidence) }, { label: "Reporting ticker", value: row.sourceTicker }] })), empty: "No primary posting evidence is available yet." },
+    },
+    chart: { label: "Open roles", unit: "roles", points: history.map((point) => ({ date: point.week, value: point.openCount })) },
+  };
+  if (detail) {
+    model.sections.table = { ...model.sections.evidence, columns: model.sections.evidence.columns.filter((entry) => entry.id !== "confidence"), empty: "No current role evidence has been captured yet." };
+  }
+  return model;
+}
+
+export function attentionSeries(model: Pick<AttentionModel, "chart">, color: string) {
+  // One or two captures are observations, not an established trend.
+  if (model.chart.points.filter((point) => point.value !== null).length < 3) return [];
+  const cadence = model.chart.unit === "roles" ? 7 * 86_400_000 : 86_400_000;
+  const points = [...model.chart.points].sort((a, b) => a.date.localeCompare(b.date)).flatMap((point, i, all) => {
+    const time = Date.parse(point.date), previous = i ? Date.parse(all[i - 1]!.date) : null;
+    const gap = previous !== null && time - previous > cadence * 1.5;
+    return [...(gap ? [scalarPoint(new Date(previous + cadence), null)] : []), scalarPoint(new Date(time), point.value)];
+  });
+  return [{ ...staticSeries(points, { id: "company-attention", label: model.chart.label, color, calendarSpaced: true }), unit: model.chart.unit, unitGroup: model.chart.unit }];
+}
+
+export function sortAttentionRows(rows: AttentionRow[], columnId: string, direction: "asc" | "desc") {
+  return [...rows].sort((a, b) => {
+    const left = a.values[columnId], right = b.values[columnId];
+    if (left == null) return right == null ? a.id.localeCompare(b.id) : 1;
+    if (right == null) return -1;
+    const result = typeof left === "number" && typeof right === "number" ? left - right : String(left).localeCompare(String(right));
+    return (direction === "asc" ? result : -result) || a.id.localeCompare(b.id);
+  });
+}
+
+const APP_COLUMNS = [column("name", "App", 27, false, true), column("symbol", "Ticker", 12), column("country", "Country", 9), column("chart", "Chart", 10), column("rank", "Rank", 7, true), column("change", "7D places", 12, true), column("rating", "Rating / 5", 12, true), column("ratings", "Ratings", 12, true), column("drift", "7D rating", 12, true), column("growth", "7D ratings", 12, true)];
+const APP_COMPANIES = [column("symbol", "Ticker", 12), column("name", "Company", 24, false, true), column("score", "Score / 100", 13, true), column("velocity", "Places / day", 14, true), column("apps", "Apps", 8, true), column("countries", "Countries", 11, true), column("drift", "7D rating", 12, true), column("growth", "7D ratings", 12, true)];
+const appCompanyRow = (row: AppCompany): AttentionRow => ({ id: row.symbol, symbol: row.symbol, values: { symbol: row.symbol, name: row.name, score: row.attentionScore, velocity: row.rankVelocity7d, apps: row.appCount, countries: row.countryCount, drift: row.ratingChange7d, growth: row.ratingCountGrowth7d } });
+export function appsModel(data: AppAttentionPayload, mix = "countries"): AttentionModel {
+  const evidence = data.evidence.map((row): AttentionRow => ({ id: `${row.revisionId}:${row.appId}`, url: row.sourceUrl, values: { name: row.name, country: row.country, chart: row.chart, rank: row.rank, observed: row.observedAt.slice(0, 10), confidence: row.confidence * 100 }, details: [{ label: "App", value: row.name }, { label: "App ID", value: row.appId }, { label: "Country / chart", value: `${row.country} / ${row.chart}` }, { label: "Rank", value: count(row.rank) }, { label: "Rating", value: row.rating?.toFixed(2) ?? "--" }, { label: "Ratings", value: count(row.ratingCount) }, { label: "Written reviews", value: count(row.reviewCount) }, { label: "Observed", value: row.observedAt }, { label: "Published", value: row.sourceUpdatedAt ?? "Unavailable" }, { label: "Revision", value: row.revisionId }, { label: "Supersedes", value: row.supersedesRevisionId ?? "Initial capture" }, { label: "Mapping confidence", value: percent(row.confidence) }, ...(row.mappingSourceUrl ? [{ label: "Ownership evidence", value: row.mappingSourceUrl }] : []), ...(row.ratingSourceUrl ? [{ label: "Rating evidence", value: row.ratingSourceUrl }] : [])] }));
+  return {
+    asOf: data.summary.lastObservedAt,
+    preview: data.access === "preview",
+    locked: Object.values(data.locked).reduce((a, b) => a + b, 0),
+    notices: [...data.coverage.limitations, ...(data.apps.some((row) => row.stale) ? ["Some app observations are stale."] : [])],
+    // Seven-day figures appear once a week of captures can give them.
+    figures: [
+      { label: "Attention score", value: data.summary.attentionScore?.toFixed(1) ?? "--", detail: "/ 100" },
+      ...(data.summary.rankVelocity7d != null ? [{ label: "Rank velocity", value: signed(data.summary.rankVelocity7d, 2), detail: "places / day" }]
+        : [{ label: "Apps", value: count(data.summary.appCount), detail: `${count(data.summary.countryCount)} countries` }]),
+      ...(data.summary.ratingChange7d != null ? [{ label: "Rating drift", value: signed(data.summary.ratingChange7d, 2), detail: "7D / 5" }] : []),
+      ...(data.summary.ratingCountGrowth7d != null ? [{ label: "Ratings added", value: signed(data.summary.ratingCountGrowth7d), detail: "7D" }] : []),
+    ],
+    sections: {
+      table: { columns: APP_COLUMNS, rows: data.apps.map((row): AttentionRow => ({ id: `${row.sourceId}:${row.appId}`, app: { store: row.store, appId: row.appId, name: row.name, country: row.country, chart: row.chart }, symbol: row.symbol ?? undefined, url: row.appUrl, values: { name: row.name, symbol: row.symbol, country: row.country, chart: row.chart, rank: row.rank, change: row.rankChange7d, rating: row.rating, ratings: row.ratingCount, drift: row.ratingChange7d, growth: row.ratingCountGrowth7d }, details: [{ label: "App", value: row.name }, { label: "Developer", value: row.developer }, { label: "Parent ticker", value: row.symbol ?? "Unmapped" }, { label: "Genres", value: row.genres.join(", ") || "--" }, { label: "Observed", value: row.observedAt }, { label: "Ratings observed", value: row.ratingObservedAt ?? "Unavailable" }, { label: "Mapping confidence", value: percent(row.confidence) }, { label: "Mapping revision", value: row.mappingRevisionId ?? "Unmapped" }, { label: "Capture revision", value: row.revisionId }] })), empty: "No app observations match these filters yet." },
+      chart: { columns: [column("date", "Date", 12), column("score", "Score / 100", 14, true), column("change", "Change", 10, true), column("apps", "Apps", 9, true), column("countries", "Countries", 12, true), column("rating", "Rating / 5", 12, true), column("ratings", "Ratings", 13, true)], rows: data.history.map((point, i, all): AttentionRow => ({ id: point.date, date: point.date, values: { date: point.date, score: point.attentionScore, change: point.attentionScore != null && all[i - 1]?.attentionScore != null ? point.attentionScore - all[i - 1]!.attentionScore! : null, apps: point.appCount, countries: point.countryCount, rating: point.rating, ratings: point.ratingCount } })).reverse(), empty: data.access === "preview" ? "Full app history requires Pro." : "History is accumulating from the first capture." },
+      mix: mix === "spreads" ? { columns: [column("name", "App", 28, false, true), column("chart", "Chart", 10), column("best", "Best country", 15), column("bestRank", "Best rank", 11, true), column("worst", "Worst country", 15), column("worstRank", "Worst rank", 12, true), column("spread", "Rank spread", 13, true)], rows: data.spreads.map((row): AttentionRow => ({ id: `${row.appId}:${row.chart}:${row.category}`, values: { name: row.name, chart: row.chart, best: row.bestCountry, bestRank: row.bestRank, worst: row.worstCountry, worstRank: row.worstRank, spread: row.spread } })), empty: "Comparable country observations are accumulating." }
+        : { columns: [column("country", "Country", 16, false, true), column("apps", "Apps", 9, true), column("ranked", "Ranked apps", 13, true), column("score", "Score / 100", 14, true), column("velocity", "Places / day", 15, true), column("date", "Observed", 12)], rows: data.countries.map((row): AttentionRow => ({ id: row.country, values: { country: row.country, apps: row.appCount, ranked: row.rankedApps, score: row.attentionScore, velocity: row.rankVelocity7d, date: row.observedAt.slice(0, 10) } })), empty: "Country observations are not available yet." },
+      peers: { columns: APP_COMPANIES, rows: (data.symbol ? data.peers : data.companies).map(appCompanyRow), empty: "No comparable mapped companies yet." },
+      evidence: { columns: [column("name", "App", 27, false, true), column("country", "Country", 10), column("chart", "Chart", 10), column("rank", "Rank", 8, true), column("observed", "Observed", 12), column("confidence", "Confidence %", 14, true)], rows: evidence, empty: "No primary chart evidence is available yet." },
+    },
+    chart: { label: "Attention score", unit: "/100", points: data.history.map((point) => ({ date: point.date, value: point.attentionScore })) },
+  };
+}

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

@@ -0,0 +1,183 @@
+import { useCallback, useMemo, useRef } from "react";
+import { isAccessDenied } from "../../../api-client/errors";
+import { usePlanAccess } from "../../../api-client/plan-access";
+import type { AppAttentionFilter, AppAttentionPayload, AppChart } from "../../../api-client/app-attention";
+import type { HiringBoard, HiringPayload } from "../../../api-client/hiring";
+import { ChartTableHeader, DataTableView, EmptyState, KeyValueRow, PageStackView, PaneFooterScope, PaneStatusBody, QueryBar, useChartTableSelection, usePagedRows, useTableLoadMore, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, 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, ScrollBox, 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 { humanLabel, listingCell, missingCell, shareCell, signedColor, toneColor, withoutQuietColumns, type StateTone } from "../shared/research-cells";
+import { AppRankView } from "./app-rank";
+import { useAttentionEvidence } from "./evidence";
+import { cachedAttention, fetchAttention, loadAttention, validateAttention, type AttentionPayload } from "./client";
+import { appsModel, attentionSeries, count, hiringModel, sortAttentionRows, type AttentionKind, type AttentionRow, type AttentionTab } from "./model";
+
+type Size = Pick<PaneProps, "width" | "height" | "focused">;
+const rowId = (row: AttentionRow) => row.id;
+const rowDate = (row: AttentionRow) => row.date ? new Date(row.date) : null;
+/** Decimals per column: percentages and scores to one place, ratings and z-scores to two, counts whole. */
+const DECIMALS: Record<string, number> = { score: 1, remote: 1, share: 1, confidence: 0, velocity: 2, rating: 2, drift: 2, z: 2, change: 1 };
+const SIGNED_COLUMNS = new Set(["net", "change", "velocity", "drift", "growth"]);
+const SIGNAL_TONES: Record<string, StateTone> = { Surge: "positive", Freeze: "negative", Stale: "warning", Collecting: "muted", Uncovered: "muted", Ok: "text" };
+/** Columns left out while every row reads the same default: a first capture has no weekly change yet. */
+const QUIET_COLUMNS: Record<string, readonly string[]> = { net: [""], z: [""], change: [""], velocity: [""], drift: [""], growth: [""], added: [""], removed: [""], coverage: ["complete"], spread: [""] };
+const LABEL_COLUMNS = new Set(["chart"]);
+function Evidence({ row, width, height }: Size & { row: AttentionRow }) {
+  const colors = useThemeColors();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  return <ScrollBox width={width} height={desktop ? undefined : height} flexGrow={1} flexBasis={0} contentOptions={{ paddingX: 1 }}>
+    {(row.details ?? Object.entries(row.values).map(([label, value]) => ({ label, value: String(value ?? "--") }))).map((entry) => <KeyValueRow key={entry.label} label={entry.label} value={entry.value} labelWidth={22} />)}
+    {row.url ? <Box paddingY={1}><Text fg={colors.textMuted}>{row.url}</Text></Box> : null}
+  </ScrollBox>;
+}
+
+export function HiringPane(props: Size) {
+  const { symbol } = usePaneTickerIdentity();
+  return <AttentionView key={symbol ?? "board"} {...props} kind="hiring" symbol={symbol ?? undefined} />;
+}
+export function AppsPane(props: Size) {
+  const { symbol } = usePaneTickerIdentity();
+  const [appId] = usePaneSettingValue<string>("appId", "");
+  const [store] = usePaneSettingValue<string>("store", "app-store");
+  const [country] = usePaneSettingValue<string>("country", "");
+  const [chart] = usePaneSettingValue<string>("chart", "");
+  const [name] = usePaneSettingValue<string>("appRankName", appId);
+  const session = useResearchCloudSession();
+  const access = usePlanAccess();
+  const focus = useMemo(() => ({ appId, name, country: (country || (store === "google-play" ? "GLOBAL" : "US")).toUpperCase(), chart: (chart || (store === "google-play" ? "unranked" : "free")) as AppChart, store: store === "google-play" ? "google-play" as const : "app-store" as const }), [appId, name, country, chart, store]);
+  if (appId) return <AppRankView {...props} focus={focus} accessKey={`${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`} />;
+  return <AttentionView key={symbol ?? "board"} {...props} kind="apps" symbol={symbol ?? undefined} />;
+}
+
+function AttentionView({ kind, symbol, width, height, focused }: Size & { kind: AttentionKind; symbol?: string }) {
+  const colors = useThemeColors();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const host = useRendererHost();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const session = useResearchCloudSession();
+  const access = usePlanAccess();
+  const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
+  const upgrade = useCloudUpgradeAction(kind === "hiring" ? "hire" : "apps");
+  const [openingTab] = usePaneSettingValue<string>("tab", "table");
+  const [savedTab, setTab] = usePluginPaneState<string>(`${kind}:${symbol ?? "board"}:tab`, openingTab);
+  const tab: AttentionTab = ["chart", "mix", "peers", "evidence"].includes(savedTab) && (kind === "apps" || symbol) ? savedTab as AttentionTab : "table";
+  const [openingCountry] = usePaneSettingValue<string>("country", "");
+  const [country, setCountry] = usePluginPaneState<string>(`${kind}:country`, openingCountry);
+  const [openingChart] = usePaneSettingValue<string>("chart", "");
+  const [chart, setChart] = usePluginPaneState<string>(`${kind}:chart`, openingChart);
+  const [openingDays] = usePaneSettingValue<string>("days", "90");
+  const [days, setDays] = usePluginPaneState<string>(`${kind}:days`, String(openingDays));
+  const [mix, setMix] = usePluginPaneState<string>(`${kind}:mix`, kind === "hiring" ? "functions" : "countries");
+  const filters = useMemo<AppAttentionFilter>(() => kind === "apps" ? { ...(country ? { country } : {}), ...(chart ? { chart: chart as AppChart } : {}), days: Number(days) || 90 } : {}, [kind, country, chart, days]);
+  const [snapshotSetting] = usePaneSettingValue<AttentionPayload | null>("attentionSnapshot", null);
+  const snapshot = useMemo(() => { try { return snapshotSetting ? validateAttention(kind, snapshotSetting) : null; } catch { return null; } }, [kind, snapshotSetting]);
+  const loader = useCallback((force: boolean) => snapshot ? Promise.resolve({ payload: snapshot, stale: false, refreshError: null }) : loadAttention(kind, symbol, accessKey, filters, force), [kind, symbol, accessKey, filters, snapshot]);
+  const resource = useAsyncResource(loader, { initialData: () => cachedAttention(kind, symbol, accessKey, filters), clearOnError: isAccessDenied });
+  const data = resource.data?.payload;
+  const model = useMemo(() => data ? kind === "hiring" ? hiringModel(data as HiringPayload | HiringBoard, mix) : appsModel(data as AppAttentionPayload, mix) : null, [data, kind, mix]);
+  const [selectedId, setSelected] = usePluginPaneState<string | null>(`${kind}:${symbol ?? "board"}:${tab}:selected`, null);
+  const [openCompany, setOpenCompany] = usePluginPaneState<string | null>(`${kind}:${symbol ?? "board"}:company`, null);
+  const [openAppId, setOpenApp] = usePluginPaneState<string | null>(`${kind}:${symbol ?? "board"}:app`, null);
+  const [openEvidence, setOpenEvidence] = usePluginPaneState<string | null>(`${kind}:${symbol ?? "board"}:evidence`, null);
+  const [sort, setSort] = usePluginPaneState<{ column: string; direction: "asc" | "desc" }>(`${kind}:${symbol ?? "board"}:${tab}:sort`, { column: tab === "chart" ? "date" : tab === "mix" ? "count" : kind === "hiring" ? symbol ? "title" : "open" : "rank", direction: tab === "chart" || tab === "mix" || (kind === "hiring" && !symbol) ? "desc" : "asc" });
+  const section = model?.sections[tab];
+  const paginated = kind === "apps" && ["table", "evidence", "peers"].includes(tab) || kind === "hiring" && !symbol;
+  const pageLoader = useCallback(async ({ offset, signal }: { offset: number; signal: AbortSignal; force: boolean }) => {
+    const payload = offset === 0 && data ? data : await fetchAttention(kind, symbol, { ...filters, offset, limit: 100 }, undefined, signal);
+    const projected = kind === "hiring" ? hiringModel(payload as HiringPayload | HiringBoard, mix) : appsModel(payload as AppAttentionPayload, mix);
+    const nextOffset = "companies" in payload && kind === "hiring" && "total" in payload
+      ? !payload.preview && offset + payload.companies.length < payload.total ? offset + payload.companies.length : null
+      : (payload as AppAttentionPayload).page?.nextOffset ?? null;
+    return { rows: projected.sections[tab].rows, hasMore: !snapshot && nextOffset !== null, nextOffset };
+  }, [data, kind, symbol, filters, mix, tab, snapshot]);
+  const paged = usePagedRows(data && paginated ? pageLoader : null, { getId: rowId });
+  const sectionRows = paginated && paged.status !== "idle" ? paged.rows : section?.rows ?? [];
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const scrollMore = useTableLoadMore(scrollRef, paged.hasMore && !openCompany && !openEvidence, paged.loadMore);
+  const lockedCount = !data || !model?.preview ? 0 : typeof data.locked === "number" ? data.locked
+    : kind === "hiring" ? (data as HiringPayload).locked[tab === "table" || tab === "evidence" ? "evidence" : tab === "chart" ? "history" : tab === "peers" ? "peers" : mix === "signals" ? "signals" : "mix"]
+      : (data as AppAttentionPayload).locked[tab === "table" ? "apps" : tab === "chart" ? "history" : tab === "mix" ? mix === "spreads" ? "spreads" : "countries" : tab === "peers" ? symbol ? "peers" : "companies" : "evidence"];
+  const lockedRows = Math.min(3, lockedCount);
+  const rows = useMemo(() => [...sortAttentionRows(sectionRows, sort.column, sort.direction), ...Array.from({ length: lockedRows }, (_, index): AttentionRow => ({ id: `locked:${index}`, values: {} }))], [sectionRows, sort, lockedRows]);
+  useAttentionEvidence(kind, data ?? null, tab, rows.filter((row) => !row.id.startsWith("locked:")).map(rowId));
+  const dataRows = useMemo(() => rows.filter((row) => !row.id.startsWith("locked:")), [rows]);
+  // A company's own apps all carry its ticker; the column only earns its room on the board.
+  const columns = useMemo(() => !section ? [] : withoutQuietColumns(section.columns.filter((column) => !(column.id === "symbol" && kind === "apps" && symbol && tab !== "peers")),
+    dataRows, (row, id) => row.values[id] ?? "", QUIET_COLUMNS), [section, dataRows, kind, symbol, tab]);
+  const maxShare = Math.max(0, ...dataRows.map((row) => typeof row.values.share === "number" ? row.values.share : 0));
+  const selected = rows.find((row) => row.id === selectedId) ?? rows[0] ?? null;
+  const evidence = rows.find((row) => row.id === openEvidence) ?? null;
+  const app = rows.find((row) => row.id === openAppId)?.app ?? null;
+  const detailOpen = !!openCompany || !!evidence || !!app;
+  const tabs = [{ value: "table", label: "Table" }, ...(kind === "apps" || symbol ? [{ value: "chart", label: "Chart" }, { value: "mix", label: kind === "hiring" ? "Mix" : "Markets" }, { value: "peers", label: kind === "apps" && !symbol ? "Companies" : "Peers" }, { value: "evidence", label: "Evidence" }] : [])];
+  const { strip, rows: tabRows } = usePaneTabs(model && !openCompany && !app ? { tabs, activeValue: tab, onSelect: (value) => { setTab(value); setOpenEvidence(null); }, focused, dense: true } : null);
+  const bodyHeight = Math.max(3, height - tabRows);
+  const series = useMemo(() => model ? attentionSeries(model, colors.textBright) : [], [model, colors.textBright]);
+  const chartSelection = useChartTableSelection({ rows, getId: rowId, getDate: rowDate, selectedId: selected?.id ?? null, onSelect: setSelected, focused: focused && !detailOpen, enabled: tab === "chart" });
+  useAutoRefresh(resource.updatedAt, resource.load);
+  usePaneRefreshKey(() => { void resource.reload(); paged.reload(); }, { focused: focused && !detailOpen });
+  const selectedSymbol = selected?.symbol ?? symbol;
+  const source = evidence?.url ?? selected?.url;
+  const hints: PaneHint[] = [
+    ...(source ? [{ id: "source", key: "o", label: "pen source", onPress: () => void host.openExternal(source) }] : []),
+    ...(selected && !evidence && selected.details ? [{ id: "evidence", key: "e", label: "vidence", onPress: () => setOpenEvidence(selected.id) }] : []),
+    ...(selected?.app && selectedSymbol && !symbol ? [{ id: "company", key: "c", label: "ompany", onPress: () => setOpenCompany(selectedSymbol) }] : []),
+    ...(selectedSymbol ? [
+      { id: "description", key: "d", label: "es", onPress: () => createPaneFromTemplate("new-ticker-detail-pane", { symbol: selectedSymbol }) },
+      { id: "financials", key: "f", label: "a", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol: selectedSymbol }) },
+      { id: "chart", key: "g", label: "raph", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: selectedSymbol }) },
+      { id: "related", key: "a", label: kind === "hiring" ? "pps" : " hiring", title: kind === "hiring" ? "App attention" : "Hiring momentum", onPress: () => createPaneFromTemplate(kind === "hiring" ? "apps-pane" : "hiring-pane", { symbol: selectedSymbol }) },
+    ] : []),
+    ...(model?.preview ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: upgrade }] : []),
+  ];
+  usePaneStatusFooter({ registrationId: `${kind}:status`, enabled: !openCompany && !app, loading: resource.loading || paged.loadingMore, error: data ? resource.error ?? paged.moreError?.message ?? paged.error?.message : null, stale: resource.data?.stale,
+    info: [...(model?.asOf ? [{ id: "observed", parts: [{ text: `as of ${model.asOf.slice(0, 10)}`, tone: "muted" as const }] }] : []), ...(model?.preview ? [{ id: "preview", parts: [{ text: "Pro preview", tone: "warning" as const }] }] : [])], hints });
+  usePaneNoticeFooter({ registrationId: `${kind}:notices`, enabled: !openCompany && !app, focused, notices: [...(model?.notices ?? []), ...(resource.data?.refreshError ? [resource.data.refreshError] : [])] });
+  if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement={kind === "hiring" ? "hiring-momentum-signin" : "app-attention-signin"} action={kind === "hiring" ? "view hiring momentum" : "view app attention"} needsVerification={session.needsVerification} />;
+  const countryOptions = data && kind === "apps" ? (data as AppAttentionPayload).coverage.configuredCountries : [];
+  const query = kind === "hiring" && tab !== "mix" ? undefined : <QueryBar width={width} filters={kind === "apps" ? [
+    { id: "country", label: "Country", value: country, defaultValue: "", options: [{ value: "", label: "All countries" }, ...countryOptions.map((value) => ({ value, label: value }))], onChange: setCountry },
+    { id: "chart", label: "Chart", value: chart, defaultValue: "", options: [{ value: "", label: "All charts" }, { value: "free", label: "Free" }, { value: "paid", label: "Paid" }, { value: "unranked", label: "Unranked" }], onChange: setChart },
+    ...(tab === "chart" ? [{ id: "days", label: "Window", value: days, options: ["30", "90", "365", "730"].map((value) => ({ value, label: `${value}D` })), onChange: setDays }] : []),
+    ...(tab === "mix" ? [{ id: "mix", label: "View", value: mix, options: [{ value: "countries", label: "Countries" }, { value: "spreads", label: "Rank spreads" }], onChange: setMix }] : []),
+  ] : tab === "mix" ? [{ id: "mix", label: "Group", value: mix, options: [{ value: "functions", label: "Role family" }, { value: "seniority", label: "Seniority" }, { value: "countries", label: "Countries" }, { value: "locations", label: "Locations" }, { value: "signals", label: "Signals" }], onChange: setMix }] : []} />;
+  return <Box width={width} height={height} flexDirection="column">
+    {strip}
+    <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} subject={kind === "hiring" ? "hiring momentum" : "app attention"}>
+      {model && section ? <PageStackView focused={focused} detailOpen={detailOpen} onBack={() => { setOpenCompany(null); setOpenEvidence(null); setOpenApp(null); }} detailTitle={openCompany ?? app?.name ?? (evidence ? String(evidence.values.title ?? evidence.values.name ?? evidence.id) : undefined)}
+        detailContent={openCompany ? <PaneFooterScope active><AttentionView key={openCompany} kind={kind} symbol={openCompany} width={width} height={bodyHeight - 1} focused={focused} /></PaneFooterScope> : app ? <AppRankView focus={app} accessKey={accessKey} width={width} height={bodyHeight - 1} focused={focused} /> : evidence ? <Evidence row={evidence} width={width} height={bodyHeight - 1} focused={focused} /> : null}
+        rootContent={<DataTableView columns={columns} items={rows} rootWidth={width} rootHeight={bodyHeight} focused={focused && !detailOpen} scrollRef={scrollRef} onBodyScrollActivity={scrollMore}
+          rootBefore={<ChartTableHeader width={width} height={bodyHeight} tableRows={rows.length} tableColumns={columns} query={query} figures={model.figures}
+            chart={tab === "chart" ? { series, ...chartSelection, formatValue: (value) => kind === "hiring" ? count(value) : value.toFixed(1), empty: series.length ? undefined : model.preview ? "Full history requires Pro." : "Collecting history", remoteKind: `${kind}-history` } : null} />}
+          selection={{ kind: "id", selectedId: selected?.id ?? null, getId: rowId, onChange: setSelected }} getItemKey={rowId}
+          sortColumnId={sort.column} sortDirection={sort.direction} onHeaderClick={(column) => setSort((old) => ({ column, direction: old.column === column && old.direction === "desc" ? "asc" : "desc" }))}
+          onActivate={(row) => row.id.startsWith("locked:") ? void upgrade() : row.app ? setOpenApp(row.id) : row.symbol && row.symbol !== symbol && (tab === "peers" || !symbol) ? setOpenCompany(row.symbol) : row.details ? setOpenEvidence(row.id) : row.url ? void host.openExternal(row.url) : undefined}
+          renderCell={(row, column, _index, state) => {
+            if (row.id.startsWith("locked:")) {
+              if (!desktop && column.id === columns[0]?.id && row.id === "locked:0") return { text: "Upgrade for all observations", content: <UpgradeLabel text="Upgrade for all observations" onPress={upgrade} role="attention-upgrade" /> };
+              return desktop ? { text: "", content: <Blurred><Text fg={colors.textDim}>Hidden</Text></Blurred> } : { text: "░░░░", color: colors.textDim };
+            }
+            const value = row.values[column.id];
+            if (value == null || value === "") return missingCell(colors);
+            if (column.id === "symbol" && typeof value === "string") return listingCell(value, colors, state.selected);
+            if (column.id === "signal" && typeof value === "string") return { text: value, color: toneColor(SIGNAL_TONES[value] ?? "text", colors), keepColorWhenSelected: value === "Surge" || value === "Freeze" };
+            const numeric = typeof value === "number";
+            const decimals = DECIMALS[column.id] ?? 0;
+            const text = numeric ? `${SIGNED_COLUMNS.has(column.id) && value > 0 ? "+" : ""}${value.toLocaleString("en-US", { minimumFractionDigits: decimals, maximumFractionDigits: decimals })}` : LABEL_COLUMNS.has(column.id) ? humanLabel(value) : column.id === "title" ? value.trim() : value;
+            if (column.id === "share" && numeric && tab === "mix") return { ...shareCell(text, maxShare ? value / maxShare : null, column.width, colors, state.selected, desktop), value };
+            return { text, value, color: numeric && SIGNED_COLUMNS.has(column.id) ? signedColor(value, colors)
+              : column.id === "name" || column.id === "title" ? colors.textBright : column.id === "date" || column.id === "observed" || column.id === "confidence" ? colors.textDim : colors.text };
+          }} selectedTextOverridesCellColor showHorizontalScrollbar resetScrollKey={`${kind}:${symbol}:${tab}:${mix}:${country}:${chart}`}
+          emptyStateTitle={section.empty} bodyAfter={lockedRows && desktop ? <LockedOverlay rows={lockedRows} text="Upgrade for all observations" onPress={upgrade} role="attention-upgrade" /> : undefined} />}
+      /> : <EmptyState title="Observations are not available yet." />}
+    </PaneStatusBody>
+  </Box>;
+}

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

@@ -0,0 +1,92 @@
+import { apiClient } from "../../../api-client";
+import type { GuidancePayload, KpiEvidence, KpiGuidance, KpiObservation, KpiPeriod, KpiQueryOptions, KpisPayload } from "../../../api-client/company-kpis";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+
+export type CompanyDataset = KpisPayload | GuidancePayload;
+export type CompanyMode = "kpis" | "guidance";
+export const KPI_UNAVAILABLE = "Company disclosures are not available yet.";
+export const companyKpisCache = createPluginCache<CompanyDataset>({ kind: "company-kpis", source: "gloom-cloud", schemaVersion: 1,
+  policy: { staleMs: 60 * 60_000, expireMs: 30 * 86_400_000 } });
+const finite = (value: unknown): value is number => typeof value === "number" && Number.isFinite(value);
+const text = (value: unknown): value is string => typeof value === "string";
+const nullableText = (value: unknown) => value === null || text(value);
+const date = (value: unknown) => text(value) && /^\d{4}-\d{2}-\d{2}$/.test(value) && Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+const instant = (value: unknown) => text(value) && Number.isFinite(Date.parse(value));
+const count = (value: unknown) => Number.isInteger(value) && Number(value) >= 0;
+const confidence = (value: unknown) => finite(value) && value >= 0 && value <= 1;
+const nullableNumber = (value: unknown) => value === null || finite(value);
+const units = ["currency", "currency_per_share", "currency_per_unit", "percent", "basis_points", "count", "ratio", "volume"];
+const bases = ["reported", "adjusted", "constant_currency", "organic"];
+const sourceKinds = ["press_release", "filing", "transcript", "opendart", "ir", "esef", "edinet"];
+const record = (value: unknown): value is Record<string, unknown> => !!value && typeof value === "object" && !Array.isArray(value);
+function validPeriod(period: KpiPeriod): boolean {
+  return !!period && (period.end === null || date(period.end)) && (period.start === null || date(period.start) && (period.end === null || period.start <= period.end))
+    && ["quarter", "half", "year", "ytd", "instant", "other"].includes(period.kind) && text(period.label)
+    && (period.fiscalYear === null || Number.isInteger(period.fiscalYear))
+    && (period.fiscalQuarter === null || [1, 2, 3, 4].includes(period.fiscalQuarter));
+}
+function validEvidence(evidence: KpiEvidence): boolean {
+  let safeUrl = false;
+  try { safeUrl = ["https:", "http:"].includes(new URL(evidence.url).protocol); } catch { /* Invalid evidence cannot be opened. */ }
+  return !!evidence && text(evidence.id) && text(evidence.documentId) && text(evidence.sourceId)
+    && sourceKinds.includes(evidence.sourceKind) && safeUrl && text(evidence.title) && instant(evidence.publishedAt)
+    && text(evidence.country) && text(evidence.language) && text(evidence.quote) && evidence.quote.trim().length > 0
+    && count(evidence.quoteOffset) && Number.isInteger(evidence.quoteSourceLength) && evidence.quoteSourceLength > 0
+    && ["exact", "whitespace", "nfkc_whitespace"].includes(evidence.quoteMatchMode) && confidence(evidence.confidence);
+}
+function validRow(row: KpiObservation | KpiGuidance): boolean {
+  return !!row && text(row.id) && text(row.symbol) && text(row.metricId) && !!row.metric && row.metric.id === row.metricId
+    && text(row.metric.name) && text(row.metric.definition) && units.includes(row.unit) && bases.includes(row.basis)
+    && nullableText(row.currency) && (!row.unit.startsWith("currency") || !!row.currency)
+    && record(row.dimensions) && Object.values(row.dimensions).every(text) && validPeriod(row.period)
+    && instant(row.asOf) && text(row.seriesKey) && confidence(row.confidence) && count(row.revision)
+    && nullableText(row.supersedesId) && typeof row.current === "boolean" && Array.isArray(row.evidence)
+    && row.evidence.length > 0 && row.evidence.every(validEvidence);
+}
+function validObservation(row: KpiObservation) { return validRow(row) && finite(row.value) && typeof row.conflict === "boolean" && (row.contested === undefined || typeof row.contested === "boolean")
+  && (row.valueQualifier === undefined || ["exact", "approximately", "at_least", "at_most", "greater_than", "less_than"].includes(row.valueQualifier)); }
+function validGuidance(row: KpiGuidance) {
+  return validRow(row) && date(row.issuedDate) && [row.low, row.high, row.point, row.midpointChangePct].every(nullableNumber)
+    && (row.low === null || row.high === null || row.low <= row.high)
+    && ["exact", "approximately", "at_least", "at_most", "greater_than", "less_than", "qualitative", "withdrawn"].includes(row.hedge)
+    && ["active", "withdrawn"].includes(row.status) && text(row.rangeText) && nullableText(row.previousId)
+    && (row.conditions === undefined || nullableText(row.conditions))
+    && ["raised", "cut", "reiterated", "mixed", "initiated", "withdrawn", "not_comparable"].includes(row.direction)
+    && (row.actual === null || text(row.actual.observationId) && finite(row.actual.value)
+      && ["above", "below", "within"].includes(row.actual.outcome) && ["beat", "miss", "in_line", "neutral"].includes(row.actual.favorable)
+      && finite(row.actual.difference) && nullableNumber(row.actual.differencePct));
+}
+export function validateCompanyData<T extends CompanyDataset>(data: T): T {
+  const coverage = data?.coverage;
+  const common = !!data && text(data.symbol) && ["available", "unavailable"].includes(data.status)
+    && (data.asOf === null || instant(data.asOf)) && ["full", "preview"].includes(data.access)
+    && count(data.lockedRows) && count(data.totalRows) && typeof data.truncated === "boolean"
+    && (data.previewRows === null || count(data.previewRows)) && text(data.methodology)
+    && !!coverage && [coverage.documents, coverage.observations, coverage.guidance, coverage.conflicts].every(count)
+    && Array.isArray(coverage.languages) && coverage.languages.every(text) && Array.isArray(coverage.sourceKinds)
+    && coverage.sourceKinds.every((kind) => sourceKinds.includes(kind)) && Array.isArray(data.dictionary);
+  const valid = common && ("series" in data
+    ? Array.isArray(data.series) && data.series.every((series) => !!series && text(series.key) && validObservation(series.latest) && series.latest.seriesKey === series.key
+      && Array.isArray(series.observations) && series.observations.every((row) => validObservation(row) && row.seriesKey === series.key))
+      && Array.isArray(data.revisions) && data.revisions.every(validObservation)
+    : Array.isArray(data.guidance) && data.guidance.every(validGuidance) && Array.isArray(data.history) && data.history.every(validGuidance));
+  if (!valid) throw new Error("The server returned unreadable company disclosures");
+  return data;
+}
+type CompanyClient = Pick<typeof apiClient, "getCloudCompanyKpis" | "getCloudCompanyGuidance">;
+export async function fetchCompanyData(mode: CompanyMode, symbol: string, options: KpiQueryOptions = {}, client: CompanyClient = apiClient) {
+  try {
+    const data = validateCompanyData(await (mode === "kpis" ? client.getCloudCompanyKpis(symbol, options) : client.getCloudCompanyGuidance(symbol, options)));
+    if (("series" in data) !== (mode === "kpis") || data.symbol.toUpperCase() !== symbol.trim().toUpperCase()) throw new Error("Company disclosures do not match the requested company");
+    return data;
+  }
+  catch (error) { throw unavailableOnServer(error, KPI_UNAVAILABLE, [404, 503]); }
+}
+export const companyQuery = (options: Record<string, unknown>): KpiQueryOptions => Object.fromEntries(["metric", "basis", "from", "to", "asOf"]
+  .flatMap((key) => typeof options[key] === "string" && options[key] !== "all" ? [[key, options[key]]] : [])) as KpiQueryOptions;
+// Partition paid history by both identity and entitlement, including screenshot snapshots.
+const cacheKey = (mode: CompanyMode, symbol: string, access: string) => `${mode}:${symbol.toUpperCase()}:${access}`;
+export const cachedCompanyData = (mode: CompanyMode, symbol: string, access: string) => cachedCloudResource(companyKpisCache, cacheKey(mode, symbol, access), validateCompanyData);
+export const loadCompanyData = (mode: CompanyMode, symbol: string, access: string, force = false) => loadCloudResource(companyKpisCache,
+  cacheKey(mode, symbol, access), () => fetchCompanyData(mode, symbol), { force, validate: validateCompanyData });

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

@@ -0,0 +1,32 @@
+import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import { companyQuery, fetchCompanyData, type CompanyMode } from "./client";
+
+export function companyHeadless(mode: CompanyMode): HeadlessPaneDefinition<"bundle"> {
+  return {
+    shape: "bundle",
+    argument: { kind: "ticker", description: "Listed company ticker, including exchange-qualified global symbols.", placeholder: "ticker" },
+    discovery: { aliases: [mode === "kpis" ? "KPIS" : "GUIDE"], dataRequirements: ["Gloom Cloud company disclosures"],
+      limitations: ["Pro dataset with a fixed latest preview on Free", "Coverage follows available company disclosures; missing data is not zero", "Compare matching definition, period, currency, basis and scope", "Fiscal labels without explicit calendar dates are retained without inferred dates"] },
+    options: [
+      { key: "tab", type: "enum", settingKey: "tab", defaultValue: "table", values: [{ value: "table" }, { value: "chart" }, ...(mode === "guidance" ? [{ value: "history" }] : []), { value: "evidence" }], description: "The pane section to render." },
+      { key: "metric", type: "string", settingKey: "metric", description: "Canonical metric ID, such as arr or subscribers." },
+      { key: "basis", type: "enum", values: [{ value: "reported" }, { value: "adjusted" }, { value: "constant_currency" }, { value: "organic" }], description: "Accounting basis filter (Pro)." },
+      { key: "from", type: "string", description: "First calendar period end, YYYY-MM-DD (Pro)." },
+      { key: "to", type: "string", description: "Last calendar period end, YYYY-MM-DD (Pro)." },
+      { key: "asOf", type: "string", description: "Point-in-time publication cutoff, YYYY-MM-DD (Pro)." },
+    ],
+    describe: (args) => `${mode === "kpis" ? "Company KPIs" : "Company guidance"} | ${args.symbols[0]}`,
+    async load(args, ctx) {
+      const options = companyQuery(args.options);
+      const data = await fetchCompanyData(mode, args.symbols[0]!, options, ctx.apiClient);
+      return { complete: !data.truncated, errors: data.truncated ? [data.access === "preview" ? "Full disclosures and history require Gloom Pro" : "Response limit reached; narrow the metric or date range"] : [],
+        sections: "series" in data ? [
+          { title: "Latest KPIs", rows: data.series.map((series) => ({ ...series.latest })) },
+          { title: "KPI history", rows: data.series.flatMap((series) => series.observations.map((row) => ({ ...row }))) },
+          { title: "Revisions and conflicts", rows: data.revisions.map((row) => ({ ...row })) },
+        ] : [{ title: "Current guidance", rows: data.guidance.map((row) => ({ ...row })) }, { title: "Guidance history", rows: data.history.map((row) => ({ ...row })) }],
+        metadata: { symbol: data.symbol, asOf: data.asOf, access: data.access, coverage: data.coverage, dictionary: data.dictionary,
+          lockedRows: data.lockedRows, totalRows: data.totalRows, methodology: data.methodology } };
+    },
+  };
+}

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

@@ -0,0 +1,26 @@
+import type { PluginModule } from "../plugin-module";
+import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
+import { companyKpisCache } from "./client";
+import { companyHeadless } from "./headless";
+import { CompanyGuidancePane, CompanyKpisPane } from "./pane";
+
+const kpisHeadless = companyHeadless("kpis");
+const guidanceHeadless = companyHeadless("guidance");
+export const companyKpisModule: PluginModule = {
+  setup(ctx) { companyKpisCache.attach(ctx.persistence); },
+  dispose() { companyKpisCache.reset(); },
+  panes: [
+    { id: "company-kpis", name: "Company KPIs", icon: "K", component: CompanyKpisPane, defaultPosition: "right", defaultMode: "floating",
+      defaultFloatingSize: { width: 130, height: 30 }, tickerFollower: true, tableExport: true, headless: kpisHeadless },
+    { id: "company-guidance", name: "Company Guidance", icon: "G", component: CompanyGuidancePane, defaultPosition: "right", defaultMode: "floating",
+      defaultFloatingSize: { width: 130, height: 30 }, tickerFollower: true, tableExport: true, headless: guidanceHeadless },
+  ],
+  paneTemplates: [
+    { ...createTickerSurfacePaneTemplate({ id: "company-kpis-pane", paneId: "company-kpis", label: "Company KPIs", shortcut: "KPIS",
+      description: "Pro company operating KPIs, comparable history, revisions and cited evidence. Free preview.",
+      keywords: ["kpis", "operating metrics", "arr", "subscribers", "backlog", "occupancy"] }), headless: kpisHeadless },
+    { ...createTickerSurfacePaneTemplate({ id: "company-guidance-pane", paneId: "company-guidance", label: "Company Guidance", shortcut: "GUIDE",
+      description: "Pro management guidance ranges, raises and cuts, actual versus guide and cited evidence. Free preview.",
+      keywords: ["guidance", "outlook", "raise", "cut", "beat", "miss"] }), headless: guidanceHeadless },
+  ],
+};