@gloom-sh/terminal 0.0.0-stage → 0.18.5

package/src/plugins/builtin/exposure/editor.tsx

@@ -0,0 +1,61 @@
+import { useRef, useState } from "react";
+import { Button, Notice, NumberField, SelectButton, TextField, useFieldRing, type SelectControl } from "../../../components";
+import { useInputCapture, useShortcut } from "../../../public/react";
+import { Box, ScrollBox, type ScrollBoxRenderable } from "../../../ui";
+import { useDialogState } from "../../../ui/dialog";
+import type { ExposureScenario } from "../../../api-client/exposure";
+import { parseCustomScenario } from "./model";
+
+export interface ExposureInputs { input: string; source: string; nav: string; cash: string; depth: number; scenario: ExposureScenario; }
+export function ExposureEditor({ initial, initialCustom, sources, focused, width, onSave, onCancel }: {
+  initial: ExposureInputs; initialCustom?: string; sources: { value: string; label: string }[]; focused: boolean; width: number;
+  onSave: (value: ExposureInputs) => void; onCancel: () => void;
+}) {
+  const [draft, setDraft] = useState(initial);
+  const first = initial.scenario.shocks[0]!;
+  const [custom, setCustom] = useState(initialCustom ?? (initial.scenario.shocks.length > 1 || !!first.transmission ? JSON.stringify(initial.scenario) : ""));
+  const [label, setLabel] = useState(initial.scenario.label);
+  const [kind, setKind] = useState(first.kind);
+  const [target, setTarget] = useState(first.target);
+  const [size, setSize] = useState(String(first.changeBps ?? first.changePct ?? -100));
+  const [products, setProducts] = useState(first.products?.join(", ") ?? "");
+  const [error, setError] = useState<string | null>(null);
+  const ids = ["source", "input", "nav", "cash", "depth", "label", "kind", "target", "size", "products", "custom", "save", "cancel"] as const;
+  type Id = typeof ids[number];
+  const [active, setActive] = useState<Id>("input");
+  const sourceControl = useRef<SelectControl>(null), kindControl = useRef<SelectControl>(null), depthControl = useRef<SelectControl>(null);
+  const scrollRef = useRef<ScrollBoxRenderable>(null);
+  const dialogOpen = useDialogState(s => s.isOpen);
+  const submit = () => {
+    try {
+      const scenario = parseCustomScenario(custom.trim() || JSON.stringify({ label, shocks: [{ id: "custom", kind, target, ...(kind === "rate" ? { changeBps: Number(size) } : { changePct: Number(size) }), ...(products.trim() ? { products: products.split(",").map(p => p.trim()).filter(Boolean) } : {}) }] }));
+      if (!size.trim() && !custom.trim()) throw new Error("Enter a shock size.");
+      if (draft.cash.trim() && (!Number.isFinite(Number(draft.cash)) || Math.abs(Number(draft.cash)) > 10)) throw new Error("Cash must be a NAV fraction between -10 and 10, for example 0.1.");
+      onSave({ ...draft, scenario });
+    } catch (e) { setError(e instanceof Error ? e.message : String(e)); }
+  };
+  const ring = useFieldRing({ ids, activeId: active, onActivate: setActive, enabled: focused && !dialogOpen, scope: "exposure-editor", scrollRef,
+    actions: { source: () => sourceControl.current?.open(), kind: () => kindControl.current?.open(), depth: () => depthControl.current?.open(), save: submit, cancel: onCancel } });
+  useInputCapture(focused);
+  useShortcut(e => { if (e.name === "escape") { e.preventDefault(); e.stopPropagation(); onCancel(); } }, { enabled: focused && !dialogOpen, phase: "before", allowEditable: true, scope: "exposure-editor" });
+  const fieldWidth = Math.max(20, width - 4);
+  const text = (id: Id, title: string, value: string, change: (v: string) => void, numeric = false) => {
+    const props = { label: title, value, onChange: change, width: fieldWidth, focused: focused && active === id, active: active === id, onMouseDown: () => setActive(id), onSubmit: submit };
+    return <Box ref={ring.nodeRef(id)}>{numeric ? <NumberField {...props} allowNegative /> : <TextField {...props} />}</Box>;
+  };
+  return <ScrollBox ref={scrollRef} flexGrow={1} flexBasis={0} minHeight={0} scrollY><Box paddingX={1} flexDirection="column" gap={1}>
+    <Box ref={ring.nodeRef("source")}><SelectButton variant="form" width={fieldWidth} label="Holdings source" value={draft.source} options={sources} onChange={source => setDraft(d => ({ ...d, source }))} controlRef={sourceControl} onFocus={() => setActive("source")} emphasized={active === "source"} /></Box>
+    {text("input", "Tickers / signed NAV weights", draft.input, input => setDraft(d => ({ ...d, input })))}
+    {text("nav", "Portfolio NAV (portfolio currency)", draft.nav, nav => setDraft(d => ({ ...d, nav })), true)}
+    {text("cash", "Cash weight (NAV fraction, optional)", draft.cash, cash => setDraft(d => ({ ...d, cash })), true)}
+    <Box ref={ring.nodeRef("depth")}><SelectButton variant="form" width={fieldWidth} label="Relationship depth" value={String(draft.depth)} options={[1, 2, 3, 4].map(n => ({ value: String(n), label: String(n) }))} onChange={depth => setDraft(d => ({ ...d, depth: Number(depth) }))} controlRef={depthControl} onFocus={() => setActive("depth")} emphasized={active === "depth"} /></Box>
+    {text("label", "Scenario name", label, setLabel)}
+    <Box ref={ring.nodeRef("kind")}><SelectButton variant="form" width={fieldWidth} label="Shock kind" value={kind} options={["country", "supplier", "customer", "commodity", "rate", "fx", "tariff"].map(value => ({ value, label: value }))} onChange={value => setKind(value as typeof kind)} controlRef={kindControl} onFocus={() => setActive("kind")} emphasized={active === "kind"} /></Box>
+    {text("target", "Country / entity / commodity / currency", target, setTarget)}
+    {text("size", kind === "rate" ? "Rate change (basis points)" : "Shock change (%)", size, setSize, true)}
+    {text("products", "Product restriction (comma separated, optional)", products, setProducts)}
+    {text("custom", "Advanced scenario JSON (overrides fields above)", custom, setCustom)}
+    {error ? <Notice tone="warning">{error}</Notice> : null}
+    <Box flexDirection="row" gap={2}><Box ref={ring.nodeRef("save")}><Button label="Analyze" variant="primary" onPress={submit} /></Box><Box ref={ring.nodeRef("cancel")}><Button label="Cancel" variant="secondary" onPress={onCancel} /></Box></Box>
+  </Box></ScrollBox>;
+}

package/src/plugins/builtin/exposure/evidence.ts

@@ -0,0 +1,42 @@
+import type { ExposurePayload } from "../../../api-client/exposure";
+import type { PaneScreenshotEvidenceHook } from "../../../cli/pane-functions/screenshot-evidence";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+import { isRecord } from "../../../utils/guards";
+import { validateExposure } from "./client";
+import { pathRows, portfolioRows, tableRows } from "./model";
+import { driverRows } from "./drivers";
+
+interface ExposureCapture { kind: "exposure"; version: 1; complete: boolean; plottedValueCount: number; payload: ExposurePayload; tab: string; view: string; rowIds: string[]; }
+export function useExposureEvidence(payload: ExposurePayload | null, tab: string, view: string, rowIds: string[]) {
+  useRemoteUiNode({ role: "chart-data", label: "Rendered exposure analysis", getMetadata: () => ({ kind: "exposure", version: 1, complete: !!payload, ready: !!payload, payload, tab, view, rowIds, plottedValueCount: rowIds.length }) });
+}
+export const exposureScreenshotEvidence: PaneScreenshotEvidenceHook<ExposureCapture> = {
+  paneId: "exposure", kind: "exposure", label: "exposure",
+  async prepare({ loadModel }) {
+    const model = await loadModel();
+    const result = model.result;
+    if (!("metadata" in result) || !isRecord(result.metadata)) throw new Error("Exposure screenshot needs its analyzed payload.");
+    const payload = validateExposure(result.metadata.payload as ExposurePayload);
+    return { settings: { exposureSnapshot: payload }, financials: payload.holdings.map(h => [h.symbol, { annualStatements: [], quarterlyStatements: [], priceHistory: [] }]) };
+  },
+  read(metadata) {
+    if (!isRecord(metadata) || metadata.kind !== "exposure" || metadata.version !== 1 || metadata.complete !== true || !["table", "drivers", "paths", "portfolio"].includes(String(metadata.tab)) || !Array.isArray(metadata.rowIds)) return null;
+    try {
+      const payload = validateExposure(metadata.payload as ExposurePayload);
+      const rows = metadata.tab === "drivers" ? driverRows(payload) : metadata.tab === "paths" ? pathRows(payload) : metadata.tab === "portfolio" ? portfolioRows(payload, String(metadata.view)) : tableRows(payload);
+      if (metadata.plottedValueCount !== rows.length || metadata.rowIds.length !== rows.length || metadata.rowIds.some(id => !rows.some(r => r.id === id))) return null;
+      return metadata as unknown as ExposureCapture;
+    } catch {
+      // Intentional ignore: malformed capture metadata cannot prove the screenshot's exposure data.
+      return null;
+    }
+  },
+  mismatches(evidence, { resolved, payload }) {
+    const snapshot = payload.config.layout.instances.find(i => i.instanceId === payload.paneId)?.settings?.exposureSnapshot;
+    return [...(JSON.stringify(evidence.payload) !== JSON.stringify(snapshot) ? ["Exposure output differs from the captured analysis"] : []),
+      ...(evidence.tab !== (resolved.options.tab ?? "table") ? ["Exposure tab does not match"] : []),
+      ...(evidence.view !== (resolved.options.view ?? "stress") ? ["Exposure concentration view does not match"] : [])];
+  },
+  unavailable: evidence => evidence?.complete ? [] : ["exposure analysis"],
+  symbols: ({ payload }) => payload.financials.map(([symbol]) => symbol),
+};

package/src/plugins/builtin/exposure/headless.ts

@@ -0,0 +1,290 @@
+import type { HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneRow } from "../../../types/plugin";
+import type { ExposureExtensionObservation, ExposurePayload, ExposureRequest, ExposureScenario } from "../../../api-client/exposure";
+import { cliTerminalWidth } from "../../../utils/cli-output";
+import { clipToDisplayWidth, displayWidth } from "../../../utils/format";
+import { fiscalLabel } from "../company-kpis/model";
+import { humanLabel } from "../shared/research-cells";
+import { freePreviewNote } from "../shared/free-preview";
+import { fetchExposure, fetchScenarios } from "./client";
+import { DEFAULT_SCENARIO, exposureCellText, LIBRARY_SCENARIO_IDS, parseCustomScenario, parseHoldings, pathRows, portfolioRows, scenarioTitle, tableRows, TABS, type ExposureRow } from "./model";
+import { portfolioHoldings, watchlistHoldings } from "./holdings";
+import { describeCollections, findNamedCollection } from "../../../portfolio/collection-name";
+import { driverAmount, driverRows, driverScope } from "./drivers";
+
+/*
+ * The text report prints each section as its pane tab draws it: exposure
+ * ranges and weights as percents, a driver's value compact with its unit
+ * (201.18B USD), its fiscal period as KPIS prints it (FY2024) and its scope in
+ * words. The title names the scenario, so a one-shock scenario needs no shock
+ * column. Every table fits 100 columns, or a narrower terminal: names and
+ * scopes take the room the figures leave and are cut at a word only when they
+ * cannot fit. Caveats print under their row; a holding's own caveats are the
+ * report's error lines. CSV, NDJSON and JSON keep the records whole.
+ */
+type CellId = Parameters<typeof exposureCellText>[1];
+type TextRow = ExposureRow & { kind?: string; note?: string | null };
+/** A column's cells, and how far it may narrow to fit: `min` lets it give way, cut at a word; `long` is a fuller form printed only when the whole table fits with it. */
+interface TextColumn { key: string; header: string; read: (row: TextRow) => string; right?: boolean; min?: number; long?: (row: TextRow) => string }
+type ColumnOptions = Omit<TextColumn, "key" | "header" | "read">;
+const REPORT_WIDTH = 100;
+/** The space the report renderer puts between columns. */
+const GAP = 2;
+
+const column = (key: string, header: string, read: TextColumn["read"], options: ColumnOptions = {}): TextColumn => ({ key, header, read, ...options });
+const cell = (id: CellId, header: string, options?: ColumnOptions) => column(id, header, row => exposureCellText(row, id), options);
+const holding = (header: string) => column("symbol", header, row => row.symbol);
+/** The narrowest a name may get before the table gives up fitting, as the report renderer allows. */
+const NAME = 8;
+const period = cell("period", "Period");
+const note: HeadlessPaneColumn = { key: "note", header: "Note", underRow: true };
+const textRows = (items: TextRow[]) => items as unknown as HeadlessPaneRow[];
+/** Caveats that belong to one row, printed under it; null prints nothing. */
+const withNotes = (items: ExposureRow[], read: (row: ExposureRow) => string[]): TextRow[] => items.map(row => ({ ...row, note: read(row).join("\n") || null }));
+
+/** Whole words that fit `width`, then an ellipsis, with no separator left dangling; a first word too long for it is cut. */
+function clipWords(text: string, width: number): string {
+  if (displayWidth(text) <= width) return text;
+  let kept = "";
+  for (const word of text.split(" ")) {
+    const next = kept ? `${kept} ${word}` : word;
+    if (displayWidth(next) > width - 1) break;
+    kept = next;
+  }
+  kept = kept.replace(/[\s·,;:(/→-]+$/, "");
+  return kept ? `${kept}…` : clipToDisplayWidth(text, width);
+}
+/** The narrowest width past `width` at which a cut cell shows more of its text. */
+function revealWidth(text: string, width: number): number {
+  const shown = clipWords(text, width);
+  for (let next = displayWidth(shown) + 1; next < displayWidth(text); next++) if (clipWords(text, next) !== shown) return next;
+  return displayWidth(text);
+}
+
+/**
+ * Column widths for `rows` within `budget`. The fuller forms print when the
+ * whole table fits with them. Otherwise the widest narrowing column gives up
+ * a cell at a time until the table fits, or each is at its floor; then the
+ * room a word cut leaves goes back, a word at a time, to the cut cell that
+ * needs the least of it.
+ */
+function fit(columns: TextColumn[], rows: TextRow[], budget: number): { read: TextColumn["read"]; width: number }[] {
+  const header = (index: number) => displayWidth(columns[index]!.header);
+  const measure = (reads: TextColumn["read"][]) => reads.map((read, index) => Math.max(header(index), ...rows.map(row => displayWidth(read(row)))));
+  const total = (widths: number[]) => widths.reduce((sum, width) => sum + width, 0) + GAP * (widths.length - 1);
+  const long = columns.map(item => item.long ?? item.read);
+  const fuller = measure(long);
+  if (total(fuller) <= budget) return columns.map((_, index) => ({ read: long[index]!, width: fuller[index]! }));
+  const reads = columns.map(item => item.read);
+  const narrowing = columns.flatMap((item, index) => item.min === undefined ? [] : [index]);
+  const floor = (index: number) => Math.max(columns[index]!.min!, header(index));
+  let widths = measure(reads);
+  for (let overflow = total(widths) - budget; overflow > 0; overflow--) {
+    const widest = narrowing.reduce((pick, index) => widths[index]! > floor(index) && (pick < 0 || widths[index]! > widths[pick]!) ? index : pick, -1);
+    if (widest < 0) break;
+    widths[widest]!--;
+  }
+  const shown = (allotted: number[]) => allotted.map((width, index) => !narrowing.includes(index) ? width
+    : Math.max(header(index), ...rows.map(row => displayWidth(clipWords(reads[index]!(row), width)))));
+  widths = shown(widths);
+  for (;;) {
+    const spare = budget - total(widths);
+    let best: { index: number; width: number } | null = null;
+    for (const index of narrowing) for (const row of rows) {
+      const text = reads[index]!(row);
+      if (displayWidth(text) <= widths[index]!) continue;
+      const width = revealWidth(text, widths[index]!);
+      if (width - widths[index]! <= spare && (!best || width - widths[index]! < best.width - widths[best.index]!)) best = { index, width };
+    }
+    if (!best) break;
+    widths = shown(widths.map((width, index) => index === best!.index ? best!.width : width));
+  }
+  return columns.map((_, index) => ({ read: reads[index]!, width: widths[index]! }));
+}
+
+/** The text report's columns for these rows, fitted when they print, to 100 columns or the terminal when it is narrower. */
+function fitted(columns: TextColumn[], rows: TextRow[], under: HeadlessPaneColumn[] = []): HeadlessPaneColumn[] {
+  const layouts = new Map<number, ReturnType<typeof fit>>();
+  const layout = () => {
+    const budget = Math.min(REPORT_WIDTH, cliTerminalWidth() ?? REPORT_WIDTH);
+    if (!layouts.has(budget)) layouts.set(budget, fit(columns, rows, budget));
+    return layouts.get(budget)!;
+  };
+  return [...columns.map((item, index): HeadlessPaneColumn => ({ key: item.key, header: item.header, ...(item.right ? { align: "right" as const } : {}),
+    format: (_value, row) => { const { read, width } = layout()[index]!; return clipWords(read(row as unknown as TextRow), width); } })), ...under];
+}
+
+function holdingColumns(data: ExposurePayload): TextColumn[] {
+  return [holding("Holding"), ...(data.scenario.shocks.length > 1 ? [cell("label", "Shock", { min: NAME })] : []), cell("basis", "Basis"),
+    cell("exposure", "Exposure %", { right: true }), cell("classification", "Evidence", { min: 10 }), cell("impact", "Stress est. %", { right: true }), period, cell("weight", "NAV wt. %", { right: true })];
+}
+const PATH_COLUMNS = [holding("Holding"), cell("label", "Path", { min: NAME }), cell("basis", "Basis"), cell("exposure", "Exposure %", { right: true }),
+  cell("classification", "Evidence", { min: 10 }), cell("impact", "Stress est. %", { right: true }), period];
+
+/** A credit line's figures repeat the instrument their scope names: "$1.0 billion revolver: drawn" reads Drawn. */
+function driverLabel(driver: ExposureExtensionObservation): string {
+  const named = Object.values(driver.dimensions ?? {}).find(value => driver.label.startsWith(`${value}: `));
+  const rest = named ? driver.label.slice(named.length + 2) : driver.label;
+  return rest.charAt(0).toUpperCase() + rest.slice(1);
+}
+/** The scope in words, after the basis when the figure is not the reported one: Adjusted · diluted. */
+function driverScopeText(driver: ExposureExtensionObservation): string {
+  return [driver.basis && driver.basis !== "reported" ? humanLabel(driver.basis) : "", driverScope(driver)].filter(Boolean).join(" · ") || "--";
+}
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+/**
+ * A disclosure's fiscal period as KPIS prints it, FY2024 or Q3 FY2026, with
+ * the date it ended (FY2024 · Sep 28, 2024) as the fuller form. The source
+ * words it freely; wording that is not a fiscal year or quarter prints as is.
+ */
+function driverPeriod(driver: ExposureExtensionObservation): { short: string; long: string } {
+  const text = driver.period?.trim() || "--";
+  const match = /^(?:full\s+)?(?:Q([1-4])\s+)?(?:fiscal(?:\s+year)?\s+|FY\s?)(\d{4})(?:\s+ended\s+(.+))?$/i.exec(text);
+  if (!match) return { short: text, long: text };
+  const quarter = match[1] ? Number(match[1]) : null;
+  const short = fiscalLabel({ period: { start: null, end: null, kind: quarter ? "quarter" : "year", fiscalYear: Number(match[2]), fiscalQuarter: quarter, label: text } });
+  const ended = /^([A-Za-z]{3})[a-z]*\.?\s+(\d{1,2}),?\s+(\d{4})$/.exec(match[3]?.trim() ?? "");
+  const month = ended && MONTHS.includes(ended[1]!.toLowerCase()) ? `${ended[1]!.charAt(0).toUpperCase()}${ended[1]!.slice(1).toLowerCase()}` : null;
+  return { short, long: month ? `${short} · ${month} ${ended![2]}, ${ended![3]}` : short };
+}
+const DRIVER_COLUMNS = [holding("Holding"), column("label", "Company driver", row => row.driver ? driverLabel(row.driver) : row.label, { min: NAME }),
+  column("value", "Value", row => row.driver ? driverAmount(row.driver) : "--", { right: true }),
+  column("period", "Period", row => row.driver ? driverPeriod(row.driver).short : "--", { min: 10, long: row => row.driver ? driverPeriod(row.driver).long : "--" }),
+  column("scope", "Scope", row => row.driver ? driverScopeText(row.driver) : "--", { min: NAME })];
+
+/**
+ * An anonymous counterparty leads with the name its filing gives it, and the
+ * Kind column already says what it is: "Undisclosed customer (Customer one)"
+ * reads "Customer one (undisclosed)", which still tells two apart when cut.
+ */
+const targetName = (row: TextRow) => {
+  const match = row.kind ? new RegExp(`^Undisclosed ${row.kind} \\((.+)\\)$`, "i").exec(row.label) : null;
+  return match ? `${match[1]} (undisclosed)` : row.label;
+};
+
+/**
+ * Stress lines are always estimates, so the unknown share of holdings under a
+ * line says how partial it is. A concentration's share is unknown or an
+ * estimate, so it says only when its bound is partial, leaving out
+ * relationships without a share. With one holding, which
+ * holdings a line covers and their weight say nothing the Holdings table does
+ * not.
+ */
+function portfolioColumns(data: ExposurePayload, concentration: boolean, items: ExposureRow[]): TextColumn[] {
+  const several = data.holdings.length > 1;
+  // Signed exposure differs from gross only where a holding is short.
+  const signed = concentration && items.some(row => JSON.stringify(row.impact) !== JSON.stringify(row.exposure));
+  const partial = (row: ExposureRow) => row.incomplete && row.exposure !== null;
+  const holdings = several ? [holding("Holdings")] : [];
+  if (concentration) return [column("kind", "Kind", row => humanLabel(row.kind ?? "")), ...holdings, column("label", "Target", targetName, { min: NAME }),
+    cell("basis", "Basis"), cell("exposure", "Gross exp. %", { right: true }), ...(signed ? [cell("impact", "Signed exp. %", { right: true })] : []),
+    ...(items.some(partial) ? [column("bound", "Bound", row => partial(row) ? "Partial" : "")] : []), period, ...(several ? [cell("weight", "Gross wt. %", { right: true })] : [])];
+  return [...holdings, ...(data.scenario.shocks.length > 1 ? [cell("label", "Target", { min: NAME })] : []), cell("basis", "Basis"),
+    cell("exposure", "Exposure %", { right: true }), cell("impact", "Stress est. %", { right: true }), period, cell("weight", "Covered wt. %", { right: true })];
+}
+
+const CONCENTRATION_VIEWS = ["country", "supplier", "customer"] as const;
+
+/** The server's own line about a preview ("Free preview covers the first holding at depth 1. ..."): what the view is, not what failed. */
+const PREVIEW_NOTE = /^Free preview\b/i;
+
+/**
+ * A free preview's Pro line in the words every report uses, and what the
+ * server says about the preview as a note: its first sentence is the Pro
+ * line's, the rest (how the totals are weighted) stays. The other unknowns
+ * are the report's errors.
+ */
+function previewLines(data: Pick<ExposurePayload, "access" | "lockedHoldings" | "unknowns">): { lock: string[]; notes: string[]; unknowns: string[] } {
+  const preview = data.access === "preview";
+  const notes = preview ? data.unknowns.filter(line => PREVIEW_NOTE.test(line))
+    .map(line => line.replace(/^Free preview[^.]*\.\s*/i, "").trim()).filter(Boolean) : [];
+  const others = preview ? data.unknowns.filter(line => !PREVIEW_NOTE.test(line)) : data.unknowns;
+  const lock = preview ? [freePreviewNote({ shows: "the first holding, one relationship hop deep",
+    adds: `${data.lockedHoldings === 1 ? "the other holding and " : data.lockedHoldings > 1 ? `the other ${data.lockedHoldings} holdings and ` : ""}paths up to four hops` })] : [];
+  return { lock, notes, unknowns: others };
+}
+
+/** Library ids as a list: `a, b or c`. */
+function scenarioIds(library: readonly ExposureScenario[]): string {
+  const ids = library.flatMap(s => s.id ? [s.id] : []);
+  return ids.length > 1 ? `${ids.slice(0, -1).join(", ")} or ${ids.at(-1)}` : ids[0] ?? "";
+}
+
+/** An id the library does not have: the ids it does, the one it was likely meant for (`rates` for rates-up), and --custom. */
+function unknownScenarioMessage(id: string, library: readonly ExposureScenario[]): string {
+  const typed = id.trim().toLowerCase();
+  const near = typed ? library.filter(s => s.id?.split("-").includes(typed) || s.id?.startsWith(typed)) : [];
+  return [`Unknown scenario: ${id}.`, ...(near.length === 1 ? [`Did you mean ${near[0]!.id}?`] : []),
+    ...(library.length ? [`Scenarios: ${scenarioIds(library)}.`] : []), "Or describe your own with --custom."].join(" ");
+}
+
+/** The note a report run on the default scenario carries: which one it is, and how to pick another. */
+function defaultScenarioNote(scenario: ExposureScenario, library: readonly ExposureScenario[]): string {
+  const others = library.filter(s => s.id !== scenario.id);
+  return `${scenario.label} (${scenario.id}) is the default scenario. Pick another with --scenario${others.length ? ` (${scenarioIds(others)})` : ""}, or describe your own with --custom.`;
+}
+
+export const exposureHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  freshness: { status: "not-a-feed", basis: "company disclosures" },
+  argument: { kind: "free-text", optional: true, placeholder: "AAPL=60% NVDA=40%", description: "Tickers, signed NAV weights, PORT:<id>, or WATCH:<id>. Unweighted lists and watchlists use equal weights." },
+  discovery: { aliases: ["EXPO"], dataRequirements: ["Gloom Cloud geographic revenue, disclosed supply chains, KPIs, guidance and credit disclosures", "Portfolio NAV for local PORT weights"],
+    limitations: ["Pro: full holdings and up to four-hop paths; free: one holding, one hop.", "Operating exposure estimates, never predicted stock returns.", "Missing relationships and sensitivities remain unknown.", "Basis and reporting period are kept separate."] },
+  options: [
+    { key: "scenario", type: "string", settingKey: "scenario", defaultValue: DEFAULT_SCENARIO.id!, values: LIBRARY_SCENARIO_IDS.map(value => ({ value })),
+      description: "Library scenario id, or use --custom." },
+    { key: "custom", type: "string", settingKey: "customScenario", description: "JSON scenario with label and shocks; supports multiple shocks and explicit transmission assumptions." },
+    { key: "depth", type: "integer", settingKey: "depth", defaultValue: 2, minimum: 1, maximum: 4, description: "Maximum relationship hops." },
+    { key: "nav", type: "string", settingKey: "nav", description: "Positive portfolio NAV in its configured currency; required for PORT." },
+    { key: "cash", type: "string", settingKey: "cash", description: "Explicit cash weight as NAV fraction; no normalization." },
+    { key: "tab", type: "enum", settingKey: "tab", defaultValue: "table", values: TABS.map(t => ({ value: t.value })), description: "Pane tab." },
+    { key: "view", type: "enum", settingKey: "view", defaultValue: "stress", values: ["stress", "country", "supplier", "customer"].map(value => ({ value })), description: "Portfolio stress or concentration grouping." },
+  ],
+  describe: (args, result) => {
+    const payload = result?.metadata?.payload as ExposurePayload | undefined;
+    return `Exposure | ${args.rawArgument || "holdings"}${payload ? ` | ${scenarioTitle(payload.scenario)}` : ""}`;
+  },
+  async load(args, ctx) {
+    const input = args.rawArgument.trim();
+    const source = /^(PORT|WATCH):(.+)$/i.exec(input);
+    let holdings: ExposureRequest["holdings"];
+    if (source?.[1]?.toUpperCase() === "PORT") {
+      const local = await ctx.resolvePortfolio?.(source[2]!);
+      if (!local) throw new Error(`Unknown local portfolio: ${source[2]}.${ctx.config.portfolios.length ? ` Portfolios: ${describeCollections(ctx.config.portfolios)}.` : ""}`);
+      holdings = await portfolioHoldings(local.portfolio, local.tickers, Number(args.options.nav), ctx.marketData);
+    } else if (source) {
+      const tickers = await ctx.resolveWatchlist?.(source[2]!);
+      if (!tickers) throw new Error(`Unknown local watchlist: ${source[2]}.${ctx.config.watchlists.length ? ` Watchlists: ${describeCollections(ctx.config.watchlists)}.` : ""}`);
+      // The host reads the name in any case; membership is kept under the configured id.
+      holdings = watchlistHoldings(tickers, findNamedCollection(ctx.config.watchlists, source[2])?.id ?? source[2]!);
+    } else holdings = parseHoldings(input);
+    const id = String(args.options.scenario ?? DEFAULT_SCENARIO.id);
+    const library = args.options.custom ? [] : await fetchScenarios(ctx.apiClient);
+    const scenario = args.options.custom ? parseCustomScenario(String(args.options.custom)) : library.find(s => s.id === id);
+    if (!scenario) throw new Error(unknownScenarioMessage(id, library));
+    const cashWeight = args.options.cash === undefined ? undefined : Number(args.options.cash);
+    if (cashWeight !== undefined && (!Number.isFinite(cashWeight) || Math.abs(cashWeight) > 10)) throw new Error("Cash must be a NAV fraction between -10 and 10.");
+    if (ctx.signal.aborted) throw new Error("Exposure analysis cancelled.");
+    const data = await fetchExposure({ holdings, scenario, depth: Number(args.options.depth ?? 2), ...(cashWeight === undefined ? {} : { cashWeight }) }, ctx.apiClient);
+    const drivers = withNotes(driverRows(data), row => row.driver?.notes ?? []);
+    const stress = withNotes(portfolioRows(data, "stress"), row => row.incomplete ? row.unknowns : []);
+    const concentrations = CONCENTRATION_VIEWS.flatMap(kind => portfolioRows(data, kind).map(row => ({ ...row, kind })));
+    const holdingRows = tableRows(data), paths = pathRows(data);
+    const preview = previewLines(data);
+    // The library's first scenario runs unless another is asked for: the report says so, and what else there is.
+    const notes = [...(!args.options.custom && scenario.id === DEFAULT_SCENARIO.id ? [defaultScenarioNote(scenario, library)] : []), ...preview.notes];
+    return { complete: data.lockedHoldings === 0 && data.holdings.every(h => h.status === "quantified") && data.unknowns.length === 0,
+      errors: [...preview.lock, ...preview.unknowns], ...(notes.length ? { notes } : {}),
+      sections: [
+        { title: "Holdings", rows: data.holdings.map(h => ({ symbol: h.symbol, weight: h.weight, status: h.status, measures: h.measures, coverage: h.coverage, unknowns: h.unknowns })),
+          textColumns: fitted(holdingColumns(data), holdingRows), textRows: textRows(holdingRows) },
+        { title: "Company drivers", rows: data.holdings.flatMap(h => (h.extensions ?? []).map(row => ({ symbol: h.symbol, ...row }))),
+          textColumns: fitted(DRIVER_COLUMNS, drivers, [note]), textRows: textRows(drivers) },
+        { title: "Paths and evidence", rows: data.holdings.flatMap(h => h.components.map(c => ({ symbol: h.symbol, ...c }))),
+          textColumns: fitted(PATH_COLUMNS, paths), textRows: textRows(paths) },
+        { title: "Portfolio operating stress", rows: data.portfolio.measures.map(m => ({ ...m })),
+          textColumns: fitted(portfolioColumns(data, false, stress), stress, [note]), textRows: textRows(stress) },
+        { title: "Concentrations", rows: data.portfolio.concentrations.map(c => ({ ...c })),
+          textColumns: fitted(portfolioColumns(data, true, concentrations), concentrations), textRows: textRows(concentrations) },
+      ], metadata: { payload: data } };
+  },
+};

package/src/plugins/builtin/exposure/holdings.ts

@@ -0,0 +1,58 @@
+import type { ExposureHolding } from "../../../api-client/exposure";
+import type { DataProvider } from "../../../types/data-provider";
+import type { Portfolio, TickerRecord } from "../../../types/ticker";
+import { publicTickerKey } from "../../../utils/exchanges";
+import { resolveCurrencyUnit } from "../../../utils/currency-units";
+import { convertCurrency } from "../../../utils/format";
+import { logFailure } from "../../../utils/log-failure";
+import { getPortfolioPositionMetrics, getPortfolioQuoteDisplay, resolvePortfolioMarketValue } from "../../../portfolio/position-metrics";
+
+/** Explicit NAV preserves cash, shorts and leverage; net holdings are never used as NAV. */
+export async function portfolioHoldings(portfolio: Portfolio, tickers: TickerRecord[], nav: number, market: Pick<DataProvider, "getQuote" | "getExchangeRate">): Promise<ExposureHolding[]> {
+  if (!Number.isFinite(nav) || nav <= 0) throw new Error(`Enter positive NAV in ${portfolio.currency} for ${portfolio.name}.`);
+  const positions = tickers.filter(t => t.metadata.positions.some(p => p.portfolio === portfolio.id && p.shares !== 0));
+  if (!positions.length) throw new Error("The selected portfolio has no positions.");
+  if (positions.length > 100) throw new Error("Portfolio exceeds the 100 holding limit. Use an explicit subset with its original NAV weights.");
+  const currencies = new Set([portfolio.currency]);
+  for (const t of positions) {
+    const category = t.metadata.assetCategory?.toUpperCase();
+    if (category && !["STK", "STOCK", "EQUITY", "ETF", "FUND"].includes(category)) throw new Error(`${t.metadata.ticker}: ${category} position needs an explicit underlying exposure weight.`);
+    currencies.add(t.metadata.currency);
+    t.metadata.positions.filter(p => p.portfolio === portfolio.id).forEach(p => { if (p.currency) currencies.add(p.currency); });
+  }
+  const rates = new Map<string, number>([["USD", 1]]);
+  const majorRates = new Map<string, number>([["USD", 1]]);
+  const ensureRate = async (rawCurrency: string) => {
+    const unit = resolveCurrencyUnit(rawCurrency);
+    if (!unit.currency) throw new Error("Portfolio currency is missing.");
+    let rate = majorRates.get(unit.currency);
+    if (rate === undefined) {
+      rate = await market.getExchangeRate(unit.currency);
+      if (!Number.isFinite(rate) || rate <= 0) throw new Error(`FX unavailable for ${unit.currency}; weights were not estimated.`);
+      majorRates.set(unit.currency, rate);
+    }
+    rates.set(rawCurrency, rate / unit.divisor);
+  };
+  for (const currency of currencies) await ensureRate(currency);
+  const holdings: ExposureHolding[] = [];
+  for (const ticker of positions) {
+    const quote = await market.getQuote(ticker.metadata.ticker, ticker.metadata.exchange)
+      .catch(logFailure("exposure.holdings", "Load portfolio holding quote failed", null));
+    const currency = quote?.currency || ticker.metadata.currency;
+    if (!rates.has(currency)) await ensureRate(currency);
+    const metrics = getPortfolioPositionMetrics(ticker, portfolio.id, currency, {
+      currency: portfolio.currency, convert: (value, from) => convertCurrency(value, from, portfolio.currency, rates),
+    }, quote);
+    const active = getPortfolioQuoteDisplay(metrics, quote);
+    const value = resolvePortfolioMarketValue(metrics, active ? convertCurrency(active.price, currency, portfolio.currency, rates) : null);
+    if (!value || !Number.isFinite(value.net)) throw new Error(`Market value unavailable for ${ticker.metadata.ticker}; no partial portfolio was reweighted.`);
+    holdings.push({ symbol: publicTickerKey(ticker.metadata.ticker, ticker.metadata.exchange), weight: value.net / nav });
+  }
+  return holdings;
+}
+export function watchlistHoldings(tickers: TickerRecord[], id: string): ExposureHolding[] {
+  const list = tickers.filter(t => t.metadata.watchlists.includes(id));
+  if (!list.length) throw new Error("The selected watchlist is empty.");
+  if (list.length > 100) throw new Error("Watchlist exceeds the 100 holding limit.");
+  return list.map(t => ({ symbol: publicTickerKey(t.metadata.ticker, t.metadata.exchange), weight: 1 / list.length }));
+}

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

@@ -0,0 +1,40 @@
+import type { PaneTemplateContext, ShortcutArgError } from "../../../types/plugin";
+import { findNamedCollection, unknownCollectionArgError } from "../../../portfolio/collection-name";
+import type { PluginModule } from "../plugin-module";
+import { exposureHeadless } from "./headless";
+import { ExposurePane } from "./pane";
+
+const SOURCE = /^(PORT|WATCH):(.+)$/i;
+
+/**
+ * `EXPO PORT:Book` names a portfolio, and `WATCH:Watchlist` a watchlist, by
+ * name or id in any case, as `fn EXPO` reads them. The pane keeps its source
+ * by id (`PORT:book`), so the name is rewritten to the id it names.
+ */
+function sourceInput(arg: string, context: PaneTemplateContext): string {
+  const source = SOURCE.exec(arg.trim());
+  if (!source) return arg;
+  const prefix = source[1]!.toUpperCase();
+  const match = findNamedCollection(prefix === "PORT" ? context.config.portfolios : context.config.watchlists, source[2]);
+  return match ? `${prefix}:${match.id}` : arg;
+}
+
+/** `EXPO PORT:Nope` or `EXPO WATCH:Nope` names a portfolio or watchlist nothing has; tickers and weights are read by the pane. */
+function unknownSourceArg(arg: string, context: PaneTemplateContext): ShortcutArgError | null {
+  const source = SOURCE.exec(arg.trim());
+  if (!source) return null;
+  return source[1]!.toUpperCase() === "PORT"
+    ? unknownCollectionArgError(source[2]!, context.config.portfolios, "portfolio", (name) => `PORT:${name}`)
+    : unknownCollectionArgError(source[2]!, context.config.watchlists, "watchlist", (name) => `WATCH:${name}`);
+}
+
+export const exposureModule: PluginModule = {
+  panes: [{ id: "exposure", name: "Exposure", icon: "E", component: ExposurePane, defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 138, height: 31 }, tableExport: true, headless: exposureHeadless,
+    personalData: "holdings",
+    portableShare: { private: { params: true, settings: true, state: true } } }],
+  paneTemplates: [{ id: "exposure-pane", paneId: "exposure", label: "Exposure", description: "Pro scenario exposures across holdings, geographic revenue and supply chains, with source evidence and portfolio concentrations.",
+    keywords: ["exposure", "scenario", "stress", "portfolio", "supply", "country", "tariff", "pro"],
+    shortcut: { prefix: "EXPO", argKind: "text", argOptional: true, argPlaceholder: "AAPL=60% NVDA=40%", argError: unknownSourceArg }, headless: exposureHeadless,
+    createInstance: (context, options) => ({ params: { input: sourceInput(options?.arg ?? "", context) } }),
+  }],
+};