@gloom-sh/terminal 0.0.0-stage → 0.18.5

package/src/plugins/builtin/supply-chain/graph-pane.tsx

@@ -0,0 +1,221 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { isAccessDenied } from "../../../api-client/errors";
+import { usePlanAccess } from "../../../api-client/plan-access";
+import { DEFAULT_GRAPH_OPTIONS, type GraphOptions, type GraphPath, type GraphPayload } from "../../../api-client/supply-chain-graph";
+import type { SupplyEntity } from "../../../api-client/supply-chain";
+import { ActionRow, Badge, Button, ButtonActionScope, DataTableView, DetailScrollBody, EmptyState, KeyValueRow, Notice, NumberField, PageStackView, PaneStatusBody, QueryBar, StatGrid, TextField, usePaneNoticeFooter, usePaneStatusFooter, type DataTableColumn, type PaneHint, type QueryBarFilter, type StatItem } from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { RatioBar } from "../../../components/ui/ratio-bar";
+import { useAsyncResource, useAutoRefresh, useInputCapture, usePaneInstance, usePaneSettingValue, usePluginAppActions, usePluginPaneState, useShortcut } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import { Box, ScrollBox, Text, TextAttributes, 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 { UpgradeLabel } from "../shared/locked-rows";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { cachedGraph, graphOptions, loadGraph, validateGraph } from "./graph-client";
+import { entityKey, entityLabel, entityTicker, exposureLabel, pathLabel } from "./graph-model";
+import { SupplyGraph } from "./graph";
+import { graphEvidenceRow } from "./graph-evidence";
+import { disclosedValue, dollars, nativeValue, periodText, ROLE_COLORS, roleLabel, shareParts } from "./model";
+import { SupplySources, SupplyVerification } from "./row-evidence";
+import { evidenceDate, evidenceLabel, isUnconfirmed, trustTier } from "./trust";
+import { scrollByLines } from "../../../state/pane-scroll-registry";
+import { isPlainKey } from "../../../utils/keyboard";
+import { DATE_FIELD_EXAMPLES } from "../../../utils/calendar-date";
+import { displayWidth } from "../../../utils/format";
+import { useRemoteUiNode } from "../../../remote/semantic-tree";
+
+const PATH_COLUMNS: DataTableColumn[] = [{ id: "route", label: "Route", width: 40, align: "left" }, { id: "relationships", label: "Relationships", width: 22, align: "left" }, { id: "hops", label: "Hops", width: 6, align: "right" }, { id: "score", label: "Score", width: 9, align: "right" }, { id: "confidence", label: "Confidence", width: 12, align: "right" }, { id: "exposure", label: "Estimated exposure", width: 35, align: "left" }];
+const SOURCE_LABELS = { xbrl: "Structured filing", filing_text: "Filing text", press_release: "Company release", call: "Earnings call", news: "News", web: "Website", import: "Imported record" };
+const TIER_LABELS = { structured: "Structured", primary: "Primary", secondary: "Secondary", imported: "Imported" };
+
+function GraphInputs({ options, focused, width, onSave, onCancel }: { options: GraphOptions; focused: boolean; width: number; onSave: (options: GraphOptions) => void; onCancel: () => void }) {
+  const [fields, setFields] = useState({ minPct: String(options.minPct), minConfidence: String(options.minConfidence), limit: String(options.limit), asOf: options.asOf ?? "" });
+  const keys = ["minPct", "minConfidence", "limit", "asOf"] as const;
+  const [active, setActive] = useState<(typeof keys)[number]>("minPct"), [error, setError] = useState<string | null>(null);
+  useInputCapture(focused);
+  const submit = () => {
+    try { onSave(graphOptions({ ...options, roles: options.roles.join(","), sources: options.sources.join(","), tiers: options.tiers.join(","), ...fields })); }
+    catch (err) { setError(err instanceof Error ? err.message : String(err)); }
+  };
+  useShortcut(event => {
+    if (event.name === "tab") { event.preventDefault(); event.stopPropagation(); setActive(old => keys[(keys.indexOf(old) + (event.shift ? -1 : 1) + keys.length) % keys.length]!); }
+    else if (event.name === "escape") { event.preventDefault(); event.stopPropagation(); onCancel(); }
+  }, { enabled: focused, phase: "before", allowEditable: true, scope: "supply-graph-inputs" });
+  const labels = { minPct: "Minimum disclosed percentage (0–100)", minConfidence: "Minimum confidence (0–1)", limit: "Maximum paths / companies per section (1–50)", asOf: "Filing cutoff (blank for latest)" };
+  return <ScrollBox scrollY flexGrow={1} flexBasis={0} minHeight={0}><Box flexDirection="column" gap={1} paddingX={1}>
+    {keys.map(key => {
+      const props = { label: labels[key], value: fields[key], width: Math.min(width - 2, 47), focused: focused && active === key,
+        placeholder: key === "asOf" ? DATE_FIELD_EXAMPLES : undefined,
+        onMouseDown: () => setActive(key), onChange: (value: string) => setFields(old => ({ ...old, [key]: value })), onSubmit: submit };
+      return key === "asOf" ? <TextField key={key} {...props} /> : <NumberField key={key} {...props} allowDecimal={key !== "limit"} />;
+    })}
+    {error ? <Notice tone="warning">{error}</Notice> : null}
+    <Box flexDirection="row" gap={2}><Button label="Apply filters" variant="primary" onPress={submit} /><Button label="Cancel" variant="secondary" onPress={onCancel} /></Box>
+  </Box></ScrollBox>;
+}
+function PathEvidence({ data, path, width, focused, onRecenter }: { data: GraphPayload; path: GraphPath; width: number; focused: boolean; onRecenter: (entity: SupplyEntity) => void }) {
+  const colors = useThemeColors(), host = useRendererHost();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const scrollRef = useRef<ScrollBoxRenderable>(null);
+  useShortcut(event => {
+    const delta = isPlainKey(event, "j", "down") ? 1 : isPlainKey(event, "k", "up") ? -1 : 0;
+    if (focused && delta && scrollRef.current) { event.preventDefault(); event.stopPropagation(); scrollByLines(scrollRef.current, delta); }
+  });
+  const figures: StatItem[] = [
+    { id: "score", label: "Path score", value: path.score.toFixed(4) },
+    { id: "confidence", label: "Confidence", value: `${Math.round(path.confidence * 100)}%` },
+    { id: "exposure", label: "Estimated exposure", value: exposureLabel(path, data), detail: path.exposure ? periodText(path.exposure) : undefined, wide: true },
+  ];
+  const company = (entity: SupplyEntity) => desktop && entity.ticker ? <Badge label={entityTicker(entity)!} tone="accent" />
+    : <Text fg={entity.aggregate || entity.anonymous ? colors.textDim : colors.textBright} attributes={TextAttributes.BOLD}>{entityLabel(entity)}</Text>;
+  return <DetailScrollBody ref={scrollRef} resetScrollKey={path.id}><ButtonActionScope>
+    <StatGrid items={figures} width={Math.max(1, width - 2)} />
+    {path.linkIds.map((id, index) => {
+      const link = data.links.find(item => item.id === id)!;
+      const from = data.nodes.find(node => node.id === path.nodeIds[index])!, to = data.nodes.find(node => node.id === path.nodeIds[index + 1])!;
+      return <Box key={id} flexDirection="column" paddingTop={1}>
+        <Box flexDirection="row" height={1} gap={1} overflow="hidden">
+          <Text fg={colors.textDim}>{`${index + 1}H`}</Text>
+          {company(from)}<Text fg={colors.textMuted}>→</Text>{company(to)}
+        </Box>
+        {link.evidence.map(evidence => {
+          const row = graphEvidenceRow(evidence);
+          const share = shareParts(row, undefined, { includeReporter: true });
+          const native = nativeValue(row);
+          return <Box key={evidence.id} flexDirection="column" paddingBottom={1}>
+            <Box flexDirection="row" gap={1}><Badge tone={isUnconfirmed(row) ? "neutral" : "accent"} label={evidenceLabel(row)} />
+              {row.leadStatus === "verified" ? <Badge tone="positive" label="Verified" /> : null}</Box>
+            <KeyValueRow label="Disclosure" value={`${evidence.reporter.name} · ${roleLabel(evidence.role)}`} color={ROLE_COLORS[evidence.role]} labelWidth={20} />
+            <KeyValueRow label="Evidence class" value={`${TIER_LABELS[evidence.tier]} · ${SOURCE_LABELS[evidence.sourceKind]}`} detail={`${Math.round(evidence.confidence * 100)}% confidence`} labelWidth={20} />
+            <KeyValueRow label="Period" value={periodText(row)} detail={trustTier(row) === 1 ? `filed ${row.filedDate ?? "--"}` : `published ${evidenceDate(row)}`} labelWidth={20} />
+            {row.entityScope === "group" && !row.counterparty.aggregate ? <KeyValueRow label="Metric scope" value="Corporate group" labelWidth={20} /> : null}
+            <SupplyVerification row={row} />
+            {share ? <>
+              <Box flexDirection="row" gap={1}>
+                <KeyValueRow label="Disclosed share" value={share.value} color={ROLE_COLORS[evidence.role]} labelWidth={20} />
+                <RatioBar ratio={row.pctOfRevenue! / 100} width={8} color={ROLE_COLORS[evidence.role]} track />
+              </Box>
+              <KeyValueRow label="Share basis" value={share.basis} labelWidth={20} />
+            </> : null}
+            {native || row.usd !== null ? <KeyValueRow label="Disclosed value" value={disclosedValue(row)} labelWidth={20} /> : null}
+            {native && row.usd !== null ? <KeyValueRow label="USD amount" value={dollars(row)} labelWidth={20} /> : null}
+            <SupplySources row={row} width={width} onOpenSource={url => void host.openExternal(url)} />
+          </Box>;
+        })}
+        <ActionRow label={`Recenter on ${entityLabel(to)}`} onPress={() => onRecenter(to)} />
+      </Box>;
+    })}
+  </ButtonActionScope></DetailScrollBody>;
+}
+export function SupplyGraphPane({ symbol, tab, width, height, focused }: { symbol: string; tab: "graph" | "path"; width: number; height: number; focused: boolean }) {
+  const colors = useThemeColors(), desktop = !!useUiCapabilities().nativePaneChrome;
+  const instance = usePaneInstance(), session = useResearchCloudSession(), access = usePlanAccess();
+  const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
+  const initialOptions = useMemo(() => { try { return graphOptions(instance?.settings ?? {}); } catch { return DEFAULT_GRAPH_OPTIONS; } }, []);
+  const [options, setOptions] = usePluginPaneState<GraphOptions>("supply:graph-options", initialOptions);
+  const [focus, setFocus] = usePluginPaneState(`supply:graph-focus:${symbol}`, symbol);
+  const [target, setTarget] = usePluginPaneState(`supply:graph-target:${symbol}`, String(instance?.settings?.to ?? ""));
+  const [targetDraft, setTargetDraft] = useState(target), [targetActive, setTargetActive] = useState(false);
+  const [selectedId, setSelected] = usePluginPaneState<string | null>(`supply:graph-selected:${symbol}`, null);
+  const [selectedPathId, setSelectedPath] = usePluginPaneState<string | null>(`supply:path-selected:${symbol}`, null);
+  const [openId, setOpen] = usePluginPaneState<string | null>(`supply:path-evidence:${symbol}`, null);
+  const [collapsed, setCollapsed] = usePluginPaneState<string[]>(`supply:collapsed:${symbol}`, []);
+  const [visibleLinks, setVisibleLinks] = useState<string[]>([]);
+  const [inputsOpen, setInputsOpen] = useState(false);
+  const [snapshotSetting] = usePaneSettingValue<GraphPayload | null>("graphSnapshot", null);
+  const snapshot = useMemo(() => { try { return snapshotSetting ? validateGraph(snapshotSetting) : null; } catch { return null; } }, [snapshotSetting]);
+  const loader = useCallback((force: boolean) => snapshot ? Promise.resolve({ payload: snapshot, stale: false, refreshError: null }) : loadGraph(focus, target, options, accessKey, force), [focus, target, options, accessKey, snapshot]);
+  const resource = useAsyncResource(tab === "path" && !target ? null : loader, { initialData: () => cachedGraph(focus, target, options, accessKey), clearOnError: isAccessDenied });
+  const data = resource.data?.payload ?? null;
+  const [sort, setSort] = usePluginPaneState("supply:path-sort", { column: "score", direction: "desc" as "asc" | "desc" });
+  const paths = useMemo(() => data ? data.paths.length ? data.paths : [...data.upstream, ...data.downstream, ...data.related].map(row => options.ranking === "shortest" ? row.shortestPath : row.bestPath) : [], [data, options.ranking]);
+  const sortedPaths = useMemo(() => [...paths].sort((a, b) => {
+    const value = (path: GraphPath): number | string => sort.column === "route" && data ? pathLabel(path, data) : sort.column === "relationships" && data ? path.linkIds.map(id => data.links.find(link => link.id === id)?.relationship ?? "").sort().join(" ") : sort.column === "hops" ? path.hops : sort.column === "confidence" ? path.confidence : sort.column === "exposure" ? path.exposure?.pct ?? -1 : path.score;
+    const aValue = value(a), bValue = value(b);
+    return (typeof aValue === "string" && typeof bValue === "string" ? aValue.localeCompare(bValue) : Number(aValue) - Number(bValue)) * (sort.direction === "asc" ? 1 : -1);
+  }), [paths, data, sort]);
+  const initialPath = paths[Math.max(0, Number(instance?.settings?.route ?? 1) - 1)] ?? paths[0] ?? null;
+  const selectedPath = paths.find(path => path.id === selectedPathId) ?? paths.find(path => path.nodeIds.at(-1) === selectedId) ?? (target ? initialPath : null) ?? null;
+  const selected = (tab === "path" ? null : data?.nodes.find(node => node.id === selectedId)) ?? (selectedPath ? data?.nodes.find(node => node.id === selectedPath.nodeIds.at(-1)) : null) ?? null;
+  const openPath = paths.find(path => path.id === openId) ?? (instance?.settings?.evidence && openId !== "closed" ? initialPath : null) ?? null;
+  const openUpgrade = useCloudUpgradeAction("splc"), { createPaneFromTemplate } = usePluginAppActions(), openDescription = useOpenDescription();
+  const recenter = (entity: SupplyEntity) => { setFocus(entityKey(entity)); setTarget(""); setTargetDraft(""); setSelected(null); setSelectedPath(null); setOpen(null); setCollapsed([]); };
+  const applyTarget = (value: string) => { setTarget(value.trim()); setTargetDraft(value.trim()); setSelected(null); setSelectedPath(null); setOpen(null); setTargetActive(false); };
+  const selectNode = (id: string) => { setSelected(id); setSelectedPath(null); };
+  const details = () => { if (selectedPath) setOpen(selectedPath.id); };
+  const hints: PaneHint[] = inputsOpen ? [] : [
+    ...(!openPath ? [{ id: "inputs", key: "i", label: "nputs", onPress: () => setInputsOpen(true) }] : []),
+    ...(selectedPath && !openPath ? [{ id: "evidence", key: "e", label: "vidence", onPress: details }] : []),
+    ...(tab === "graph" && !openPath && selected && selected.id !== data?.entity?.id ? [{ id: "target", key: "p", label: "aths to target", onPress: () => applyTarget(entityKey(selected)) },
+      { id: "collapse", key: "c", label: collapsed.includes(selected.id) ? "expand" : "ollapse", onPress: () => setCollapsed(old => old.includes(selected.id) ? old.filter(id => id !== selected.id) : [...old, selected.id]) }] : []),
+    ...(!openPath && selected?.ticker ? [
+      { id: "description", key: "d", label: "es", onPress: () => openDescription(entityKey(selected)) },
+      { id: "financials", key: "f", label: "a", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol: entityKey(selected) }) },
+      { id: "chart", key: "g", label: "raph", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: entityKey(selected) }) },
+    ] : []),
+    ...(!openPath && (focus !== symbol || target) ? [{ id: "home", key: "z", label: "reset focus", onPress: () => { setFocus(symbol); applyTarget(""); setCollapsed([]); setSelected(null); } }] : []),
+    ...(data?.access === "preview" ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", onPress: openUpgrade }] : []),
+  ];
+  useAutoRefresh(resource.updatedAt, resource.load);
+  usePaneRefreshKey(() => void resource.reload(), { focused: focused && !inputsOpen && !targetActive });
+  usePaneStatusFooter({ registrationId: "supply-graph", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale, hints,
+    info: data?.asOf ? [{ id: "as-of", parts: [{ text: `as of ${data.asOf}`, tone: "muted" }] }] : [] });
+  usePaneNoticeFooter({ registrationId: "supply-graph:notices", focused, notices: [...(resource.data?.refreshError ? [resource.data.refreshError] : []),
+    ...(data && !data.search.complete ? [`Search limited: ${data.search.reasons.join(", ").replaceAll("_", " ")}. Narrow filters or reduce depth to inspect more routes.`] : []),
+    ...(data?.access === "preview" ? [`Pro preview: depth ${data.options.depth}. Upgrade for four hops and the full graph.`] : [])] });
+  useRemoteUiNode({ role: "chart-data", label: "Rendered supply chain graph", getMetadata: () => ({ kind: "supply-chain", version: 1, complete: !!data, ready: !!data, plottedValueCount: tab === "graph" ? visibleLinks.length : paths.length, payload: data, tab, evidenceOpen: !!openPath, evidenceId: openPath?.id ?? null, rowIds: tab === "graph" ? visibleLinks : paths.map(path => path.id) }) });
+  const filters: QueryBarFilter[] = [
+    { id: "target", kind: "text", label: "To", value: targetDraft, placeholder: "Ticker or id:123", onChange: setTargetDraft, onSubmit: applyTarget, focused, active: targetActive, onActiveChange: setTargetActive, width: 16 },
+    { id: "depth", label: "Hops", value: String(options.depth), options: [1, 2, 3, 4].map(value => ({ value: String(value), label: String(value) })), onChange: value => setOptions(old => ({ ...old, depth: Number(value) })) },
+    { id: "direction", label: "Direction", value: options.direction, options: [{ value: "both", label: "Both" }, { value: "upstream", label: "Upstream" }, { value: "downstream", label: "Downstream" }], onChange: value => setOptions(old => ({ ...old, direction: value })) },
+    { id: "roles", kind: "multi", label: "Roles", values: options.roles, options: ["supplier", "customer", "partner", "competitor", "investee"].map(value => ({ value, label: value[0]!.toUpperCase() + value.slice(1) })), onChange: values => setOptions(old => ({ ...old, roles: values as GraphOptions["roles"] })) },
+    { id: "tiers", kind: "multi", label: "Evidence class", values: options.tiers, options: Object.entries(TIER_LABELS).map(([value, label]) => ({ value, label })), onChange: values => setOptions(old => ({ ...old, tiers: values as GraphOptions["tiers"] })) },
+    { id: "sources", kind: "multi", label: "Evidence", values: options.sources, options: Object.entries(SOURCE_LABELS).map(([value, label]) => ({ value, label })), onChange: values => setOptions(old => ({ ...old, sources: values as GraphOptions["sources"] })) },
+  ];
+  const query = <QueryBar width={width} filters={filters} view={{ value: options.ranking, options: [{ value: "score", label: "Top score" }, { value: "shortest", label: "Shortest" }], onChange: value => setOptions(old => ({ ...old, ranking: value })) }} />;
+  if (!data && isCloudSessionRequired(resource.error)) return <SignInWall placement="supply-chain-signin" action="explore supply chain paths" needsVerification={session.needsVerification} />;
+  const detailOpen = inputsOpen || !!openPath;
+  return <PageStackView focused={focused && !targetActive} detailOpen={detailOpen} onBack={() => { setOpen("closed"); setInputsOpen(false); }} detailTitle={inputsOpen ? "Graph filters" : openPath && data ? pathLabel(openPath, data) : undefined}
+    detailContent={inputsOpen ? <GraphInputs options={options} focused={focused} width={width} onSave={value => { setOptions(value); setInputsOpen(false); }} onCancel={() => setInputsOpen(false)} /> : openPath && data ? <PathEvidence data={data} path={openPath} width={width} focused={focused} onRecenter={recenter} /> : null}
+    rootContent={<Box width={width} height={height} flexDirection="column">{query}
+      {tab === "path" && !target ? <EmptyState title="Choose a target company." hint="Enter a ticker or entity ID in To." /> : <PaneStatusBody loading={!data && resource.loading} error={!data ? resource.error : null} empty={!!data && !data.links.length} emptyTitle={target ? "No disclosed route within these filters." : "No disclosed relationships within these filters."} subject="supply chain graph">
+        {data ? tab === "graph" ? <SupplyGraph data={data} width={width} height={Math.max(4, height - 1 - (data.access === "preview" ? 1 : 0))} focused={focused && !targetActive && !detailOpen} selectedId={selectedId} selectedPath={selectedPath} collapsed={collapsed} onSelect={selectNode} onRecenter={recenter} onVisible={setVisibleLinks} />
+          : <DataTableView<GraphPath> columns={PATH_COLUMNS} items={sortedPaths} sortColumnId={sort.column} sortDirection={sort.direction} onHeaderClick={column => setSort(old => ({ column, direction: old.column === column && old.direction === "desc" ? "asc" : "desc" }))} emptyStateTitle="No disclosed route within these filters." getItemKey={path => path.id} focused={focused && !targetActive && !detailOpen} rootWidth={width} rootHeight={height - 1 - (data.access === "preview" ? 1 : 0)}
+            selection={{ kind: "id", selectedId: selectedPath?.id ?? paths[0]?.id ?? null, getId: path => path.id, onChange: id => setSelectedPath(id) }} onActivate={path => setOpen(path.id)}
+            renderCell={(path, column, _index, state) => {
+              const ink = state.selected ? colors.selectedText : colors.textBright;
+              if (column.id === "route") {
+                const text = pathLabel(path, data);
+                const route = path.nodeIds.map(id => data.nodes.find(node => node.id === id)).filter((node): node is SupplyEntity => !!node);
+                const cells = route.reduce((total, node) => total + displayWidth(entityLabel(node)) + (node.ticker ? 2 : 0), 0) + Math.max(0, route.length - 1) * 3;
+                return { text, content: desktop && route.length === path.nodeIds.length && cells <= column.width ? <Box flexDirection="row" height={1} gap={1} overflow="hidden">
+                  {route.flatMap((node, index) => [
+                    index ? <Text key={`arrow:${index}`} fg={state.selected ? colors.selectedText : colors.textMuted}>→</Text> : null,
+                    node.ticker ? <Badge key={node.id} label={entityTicker(node)!} tone="accent" color={state.selected ? colors.selectedText : undefined} />
+                      : <Text key={node.id} fg={state.selected ? colors.selectedText : node.aggregate || node.anonymous ? colors.textDim : ink}>{node.name}</Text>,
+                  ])}
+                </Box> : undefined };
+              }
+              if (column.id === "relationships") {
+                const relationships = [...new Set(path.linkIds.map(id => data.links.find(link => link.id === id)!.relationship))];
+                const label = (relationship: typeof relationships[number]) => relationship === "commerce" ? "Trade" : roleLabel(relationship);
+                return { text: relationships.map(label).join(" / "), content: <Box flexDirection="row" height={1} gap={1} overflow="hidden">
+                  {relationships.map(relationship => {
+                    const color = relationship === "commerce" ? colors.textMuted : ROLE_COLORS[relationship];
+                    return <Box key={relationship} flexDirection="row" gap={1} flexShrink={0}>
+                      {desktop ? <Box width={1} height={1} alignItems="center" justifyContent="center"><Box style={{ width: 6, height: 6, borderRadius: "50%", backgroundColor: color }} /></Box>
+                        : <Text fg={color}>●</Text>}
+                      <Text fg={state.selected ? colors.selectedText : color}>{label(relationship)}</Text>
+                    </Box>;
+                  })}
+                </Box> };
+              }
+              return { text: column.id === "hops" ? String(path.hops) : column.id === "score" ? path.score.toFixed(4) : column.id === "confidence" ? `${Math.round(path.confidence * 100)}%` : exposureLabel(path, data) };
+            }} showHorizontalScrollbar selectedTextOverridesCellColor resetScrollKey={`${focus}:${target}:${JSON.stringify(options)}`} /> : null}
+      </PaneStatusBody>}
+      {data?.access === "preview" ? <UpgradeLabel text="Upgrade for four hops and every relationship" onPress={openUpgrade} role="supply-upgrade" /> : null}
+    </Box>} />;
+}

package/src/plugins/builtin/supply-chain/graph.tsx

@@ -0,0 +1,167 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { ActionRow, Badge, Button, usePaneStatusFooter } from "../../../components";
+import { Box, ChartSurface, ScrollBox, Span, Text, TextAttributes, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
+import type { ChartVectorShape } from "../../../ui/host";
+import type { GraphPath, GraphPayload } from "../../../api-client/supply-chain-graph";
+import type { SupplyEntity, SupplyRole } from "../../../api-client/supply-chain";
+import { useThemeColors } from "../../../theme/theme-context";
+import { useShortcut } from "../../../react/input";
+import { useScrollBoxLayout } from "../../../components/use-scrollbox-layout";
+import { isPlainKey } from "../../../utils/keyboard";
+import { displayWidth } from "../../../utils/format";
+import { ClippedText } from "../../../components/ui/display";
+import { cardSurfaceStyle } from "../../../components/ui/card";
+import { useStaticChartBitmapSize } from "../../../components/chart/composite/bitmap";
+import { drawLine, fillOpaque, parseHex } from "../../../components/chart/native/raster/primitives";
+import { entityLabel, entityTicker, graphNodes } from "./graph-model";
+import { ROLE_COLORS } from "./model";
+import { blendHex } from "../../../theme/colors";
+
+export function SupplyGraph({ data, width, height, focused, selectedId, selectedPath, collapsed, onSelect, onRecenter, onVisible }: {
+  data: GraphPayload; width: number; height: number; focused: boolean; selectedId: string | null; selectedPath: GraphPath | null;
+  collapsed: string[]; onSelect: (id: string) => void; onRecenter: (entity: SupplyEntity) => void; onVisible: (ids: string[]) => void;
+}) {
+  const scrollRef = useRef<ScrollBoxRenderable>(null);
+  const colors = useThemeColors(), desktop = !!useUiCapabilities().nativePaneChrome;
+  const nodes = useMemo(() => graphNodes(data, collapsed, selectedPath), [data, collapsed, selectedPath]);
+  const [pages, setPages] = useState<Record<number, number>>({});
+  useEffect(() => setPages({}), [data]);
+  const columns = [...new Set(nodes.map(node => node.column))].sort((a, b) => a - b);
+  const cellWidth = Math.max(24, Math.floor(width / Math.max(columns.length, 1)));
+  const plotWidth = Math.max(width, columns.length * cellWidth);
+  const plotHeight = Math.max(6, height - 1);
+  const capacity = Math.max(1, Math.floor((plotHeight - 3) / 3));
+  const visible = columns.flatMap(column => {
+    const peers = nodes.filter(node => node.column === column), start = ((pages[column] ?? 0) * capacity) % Math.max(1, peers.length);
+    const page = peers.slice(start, start + capacity);
+    const required = peers.find(node => selectedPath?.nodeIds.includes(node.entity.id));
+    if (required && !page.includes(required)) page[page.length - 1] = required;
+    return page;
+  });
+  const positioned = visible.map(node => {
+    const peers = visible.filter(peer => peer.column === node.column), index = peers.findIndex(peer => peer.entity.id === node.entity.id);
+    return { ...node, x: columns.indexOf(node.column) * cellWidth + 1, y: 2 + (peers.length === 1 ? Math.floor((plotHeight - 5) / 2) : index * 3) };
+  });
+  const positions = new Map(positioned.map(node => [node.entity.id, node]));
+  const revealSelected = () => {
+    const scroll = scrollRef.current, selected = positions.get(selectedId ?? data.entity?.id ?? "");
+    if (!scroll || !selected) return;
+    const viewportWidth = scroll.viewport?.width ?? width;
+    const left = scroll.scrollLeft ?? 0;
+    if (selected.x < left) scroll.scrollLeft = Math.max(0, selected.x - 1);
+    else if (selected.x + cellWidth > left + viewportWidth) scroll.scrollLeft = selected.x + cellWidth - viewportWidth;
+  };
+  useEffect(revealSelected, [selectedId, data, cellWidth, width]);
+  useScrollBoxLayout(scrollRef, revealSelected);
+  const pathLinks = new Set(selectedPath?.linkIds ?? []);
+  const vectors: ChartVectorShape[] = data.links.flatMap(link => {
+    const from = positions.get(link.from), to = positions.get(link.to);
+    if (!from || !to) return [];
+    const left = from.x <= to.x ? from : to, right = from.x <= to.x ? to : from;
+    const highlighted = pathLinks.has(link.id);
+    const tone = ROLE_COLORS[link.relationship === "commerce" ? (left.column < 0 ? "supplier" : "customer") : link.relationship];
+    const opacity = selectedPath && !highlighted ? .15 : Math.max(.28, link.confidence);
+    const start = left.x + cellWidth - 3, end = right.x;
+    return [{ id: link.id, color: blendHex(colors.bg, tone, opacity), strokeWidth: highlighted ? 3 : 1.2,
+      points: Array.from({ length: 33 }, (_, i) => { const t = i / 32, smooth = t * t * (3 - 2 * t); return { x: (start + (end - start) * t) / plotWidth, y: (left.y + 1 + (right.y - left.y) * smooth) / plotHeight }; }) }];
+  });
+  const visibleIds = vectors.map(vector => vector.id).join("\n");
+  useEffect(() => { onVisible(visibleIds ? visibleIds.split("\n") : []); }, [visibleIds, onVisible]);
+  const bitmapSize = useStaticChartBitmapSize(plotWidth, plotHeight);
+  const vectorKey = JSON.stringify(vectors);
+  const bitmap = useMemo(() => {
+    if (desktop || !bitmapSize) return null;
+    const { pixelWidth: w, pixelHeight: h } = bitmapSize;
+    const pixels = new Uint8Array(w * h * 4); fillOpaque(pixels, parseHex(colors.bg));
+    for (const vector of vectors) for (let i = 1; i < vector.points.length; i++) {
+      const a = vector.points[i - 1]!, b = vector.points[i]!;
+      drawLine(pixels, w, h, a.x * w, a.y * h, b.x * w, b.y * h, parseHex(vector.color), vector.strokeWidth ?? 1);
+    }
+    return { width: w, height: h, pixels };
+  }, [desktop, bitmapSize, vectorKey, colors.bg]);
+  const fallback = useMemo(() => {
+    if (desktop) return [];
+    const grid = Array.from({ length: plotHeight }, () => Array.from({ length: plotWidth }, () => ({ mask: 0, color: colors.textDim })));
+    const bits = [[1, 8], [2, 16], [4, 32], [64, 128]];
+    for (const vector of vectors) for (let p = 1; p < vector.points.length; p++) {
+      const a = vector.points[p - 1]!, b = vector.points[p]!;
+      const steps = Math.ceil(Math.max(Math.abs(b.x - a.x) * plotWidth * 2, Math.abs(b.y - a.y) * plotHeight * 4)) + 1;
+      for (let i = 0; i <= steps; i++) {
+        const px = Math.floor((a.x + (b.x - a.x) * i / steps) * plotWidth * 2), py = Math.floor((a.y + (b.y - a.y) * i / steps) * plotHeight * 4);
+        const cell = grid[Math.floor(py / 4)]?.[Math.floor(px / 2)];
+        if (cell && px >= 0 && py >= 0) { cell.mask |= bits[py % 4]![px % 2]!; cell.color = vector.color; }
+      }
+    }
+    return grid.map(line => {
+      const spans: { text: string; color: string }[] = [];
+      for (const cell of line) { const char = cell.mask ? String.fromCharCode(0x2800 + cell.mask) : " "; if (spans.at(-1)?.color === cell.color) spans.at(-1)!.text += char; else spans.push({ text: char, color: cell.color }); }
+      return spans;
+    });
+  }, [desktop, plotHeight, plotWidth, vectorKey, colors.textDim]);
+  const pageColumn = positions.get(selectedId ?? "")?.column ?? columns.find(column => nodes.filter(node => node.column === column).length > capacity);
+  const pageCount = pageColumn === undefined ? 1 : Math.ceil(nodes.filter(node => node.column === pageColumn).length / capacity);
+  const advancePage = (column: number, delta: number) => {
+    const peers = nodes.filter(node => node.column === column), count = Math.ceil(peers.length / capacity);
+    const next = ((pages[column] ?? 0) + delta + count) % count;
+    setPages(old => ({ ...old, [column]: next }));
+    if (peers[next * capacity]) onSelect(peers[next * capacity]!.entity.id);
+  };
+  const page = (delta: number) => { if (pageColumn !== undefined) advancePage(pageColumn, delta); };
+  usePaneStatusFooter({ registrationId: "supply-graph:paging", enabled: focused && pageCount > 1, hints: [
+    { id: "previous-layer-page", key: "[", label: "previous companies", onPress: () => page(-1) },
+    { id: "next-layer-page", key: "]", label: "next companies", onPress: () => page(1) },
+  ] });
+  useShortcut(event => {
+    if (!focused || event.defaultPrevented || !visible.length) return;
+    const index = Math.max(0, visible.findIndex(node => node.entity.id === selectedId));
+    if (isPlainKey(event, "j", "down", "k", "up")) onSelect(visible[(index + (isPlainKey(event, "j", "down") ? 1 : -1) + visible.length) % visible.length]!.entity.id);
+    else if (isPlainKey(event, "return", "enter")) onRecenter(visible[index]!.entity);
+    else return;
+    event.preventDefault(); event.stopPropagation();
+  });
+  return <ScrollBox ref={scrollRef} width={width} height={height} flexGrow={1} flexBasis={0} minHeight={0} scrollX scrollY focusable={false}>
+    <Box width={plotWidth} height={plotHeight} flexShrink={0} position="relative">
+      <ChartSurface width={plotWidth} height={plotHeight} position="absolute" top={0} left={0} vectors={desktop ? vectors : undefined} bitmap={bitmap} aria-label="Supply chain multi-hop graph">
+        {!desktop ? fallback.map((spans, y) => <Text key={y}>{spans.map((span, i) => <Span key={i} fg={span.color}>{span.text}</Span>)}</Text>) : null}
+      </ChartSurface>
+      {columns.map((column, index) => <Box key={column} position="absolute" top={0} left={index * cellWidth + 1} width={cellWidth - 2}><Text fg={column < 0 ? ROLE_COLORS.supplier : column > 0 ? ROLE_COLORS.customer : colors.textMuted}>{column < 0 ? `${-column} HOP${column === -1 ? "" : "S"}` : column > 0 ? `${column} HOP${column === 1 ? "" : "S"}` : "FOCUS"}</Text></Box>)}
+      {columns.map((column, index) => {
+        const count = nodes.filter(node => node.column === column).length;
+        return count > capacity ? <Box key={`page:${column}`} position="absolute" top={plotHeight - 1} left={index * cellWidth + 1} width={cellWidth - 2}><ActionRow label="Next companies" onPress={() => advancePage(column, 1)} /></Box> : null;
+      })}
+      {positioned.map(node => {
+        const relationship = data.links.find(link => node.path?.linkIds.includes(link.id) && link.relationship !== "commerce")?.relationship;
+        const role: SupplyRole | null = !node.hops ? null : node.related && relationship && relationship !== "commerce" ? relationship : node.column < 0 ? "supplier" : "customer";
+        const accent = role ? ROLE_COLORS[role] : colors.textMuted;
+        const active = node.entity.id === selectedId, company = !node.entity.aggregate && !node.entity.anonymous;
+        const kind = node.entity.aggregate ? "group" : node.entity.anonymous ? "undisclosed" : null;
+        const inner = cellWidth - 5;
+        const ticker = entityTicker(node.entity);
+        const tickerWidth = ticker ? displayWidth(ticker) + 3 : 0;
+        const showTicker = company && tickerWidth > 0 && inner >= tickerWidth + 5;
+        const prefix = collapsed.includes(node.entity.id) ? "+ " : "";
+        const name = prefix + (showTicker ? node.entity.name : entityLabel(node.entity));
+        const nameWidth = inner - (showTicker ? tickerWidth : 0);
+        const relation = kind ?? (node.related ? `${node.hops > 1 ? "via " : ""}${role}` : role);
+        const confidence = `${Math.round((node.path?.confidence ?? 0) * 100)}%`;
+        const detail = node.hops ? `${node.hops}H · ${relation}${inner >= displayWidth(relation ?? "") + 12 ? ` · ${confidence}` : ""}` : showTicker ? "Focus company" : node.entity.name;
+        return <Box key={node.entity.id} position="absolute" left={node.x} top={node.y} width={cellWidth - 3} height={2} zIndex={10} flexDirection="column" overflow="hidden"
+          backgroundColor={desktop ? undefined : active ? colors.selected : node.hops ? blendHex(colors.bg, accent, 0.12) : colors.panel}
+          // The flow's card (flow.tsx): in the relationship's colour, the focus company plain.
+          style={desktop ? { ...cardSurfaceStyle({ selected: active, accent: role ? accent : undefined, padding: "0 0 0 var(--gloom-space-sm)" }), cursor: "pointer" } : undefined}
+          onMouseOver={() => onSelect(node.entity.id)} data-gloom-role="supply-graph-node">
+          <Button label={`${prefix}${entityLabel(node.entity)}`} title={node.entity.name} variant="plain" compact flush stopPropagation height={2} width={cellWidth - (desktop ? 5 : 3)} onPress={() => onRecenter(node.entity)}>
+            <Box flexDirection="column" width="100%">
+              <Box flexDirection="row" height={1} gap={desktop ? 1 : 0} overflow="hidden">
+                {!desktop ? <Text fg={accent}>▍</Text> : null}
+                <ClippedText fg={active && !desktop ? colors.selectedText : company ? colors.textBright : colors.textDim} attributes={company ? TextAttributes.BOLD : 0} text={name} width={nameWidth} />
+                {showTicker ? desktop ? <Badge label={ticker!} tone="accent" /> : <Text fg={active ? colors.selectedText : colors.textDim}>{` ${ticker}`}</Text> : null}
+              </Box>
+              <Box height={1} paddingLeft={desktop ? 0 : 1} overflow="hidden"><ClippedText fg={active && !desktop ? colors.selectedText : colors.textDim} text={detail} width={inner} /></Box>
+            </Box>
+          </Button>
+        </Box>;
+      })}
+    </Box>
+  </ScrollBox>;
+}

package/src/plugins/builtin/supply-chain/headless.ts

@@ -0,0 +1,185 @@
+import type { SupplyRow } from "../../../api-client/supply-chain";
+import { DATE_OPTION_EXAMPLES, isoDateOption } from "../../../utils/calendar-date";
+import type { GraphEvidence, GraphPath, GraphPayload } from "../../../api-client/supply-chain-graph";
+import type { HeadlessBundleResult, HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneDefinition, HeadlessPaneRow } from "../../../types/plugin";
+import { fetchSupplyChain } from "./client";
+import { evidenceDate, evidenceLabel, isUnconfirmed, matchesSupplyOptions, supplyOptions, trustTier } from "./trust";
+import { fetchSupplyGraph, graphOptions } from "./graph-client";
+import { entityTicker, exposureLabel, pathLabel } from "./graph-model";
+import { graphEvidenceRow } from "./graph-evidence";
+import { counterpartyName, disclosedValue, disclosureText, earlierRows, isTaggedFact, lockedDisclosures, nativeValue, periodText, roleLabel, shareParts, supplyPreviewNote, supplyRoleCounts } from "./model";
+
+/**
+ * The Table tab's columns, printed as the pane prints them: the share with
+ * what it is a share of (31.5% of AIRI revenue), the value in its disclosed
+ * currency and scale (53,412,000,000 USD), and Value only when a row has one.
+ * Each printed row reads the relationship it was exported from; the exported
+ * rows keep every field, quotes and evidence included.
+ */
+function tableColumns(rows: HeadlessPaneRow[], sources: ReadonlyMap<HeadlessPaneRow, SupplyRow>, focusId: string | undefined): HeadlessPaneColumn[] {
+  const cell = (read: (row: SupplyRow) => string | null) => (value: unknown, row: HeadlessPaneRow) => {
+    const source = sources.get(row);
+    return (source ? read(source) : value == null ? null : String(value)) ?? "-";
+  };
+  const valued = rows.some((row) => { const source = sources.get(row); return !!source && (nativeValue(source) !== null || source.usd !== null); });
+  const lengths = rows.some((row) => sources.get(row)?.periodMonths != null);
+  return [
+    { key: "counterparty", header: "Counterparty", format: cell(counterpartyName) },
+    { key: "evidenceTier", header: "Evidence" },
+    { key: "ticker", header: "Ticker" },
+    { key: "role", header: "Role", format: cell((row) => roleLabel(row.role)) },
+    // Exports keep the share a number; the text says what it is a share of.
+    { key: "pct", header: "Share", format: cell((row) => shareParts(row, focusId)?.value ?? null),
+      textFormat: cell((row) => { const share = shareParts(row, focusId); return share ? `${share.value} ${share.basis}` : null; }) },
+    ...(valued ? [{ key: "usd", header: "Value", align: "right" as const,
+      format: cell((row) => nativeValue(row) === null && row.usd === null ? null : disclosedValue(row).replace(/ (disclosed|derived)$/, "")) }] : []),
+    // Exports keep the end date; the text adds the period's length when the source states it.
+    // A narrow table may cut the length as it cuts other text, never the date (eleven cells: the date and an ellipsis).
+    { key: "period", header: "Period", textFormat: cell(periodText), ...(lengths ? { minWidth: 11 } : {}) },
+    { key: "filed", header: "Published", format: cell(evidenceDate) },
+  ];
+}
+
+const pathColumns = [
+  { key: "route", header: "Route" }, { key: "hops", header: "Hops" },
+  { key: "score", header: "Rank score", description: "Product of normalized edge weights; not a probability." },
+  { key: "confidence", header: "Confidence" }, { key: "exposureLabel", header: "Estimated exposure" },
+];
+/**
+ * What a graph disclosure says in words: the text itself, or for a tagged
+ * XBRL fact the sentence a filing-text disclosure of the same link quotes,
+ * else the fact read out ("Customer, Gold, revenue").
+ */
+function graphStatement(item: GraphEvidence, siblings: readonly GraphEvidence[]): string {
+  const row = graphEvidenceRow(item);
+  if (!isTaggedFact(row)) return item.quote;
+  const sentence = siblings.find((other) => other.id !== item.id && other.sourceKind === "filing_text" && other.reporter.id === item.reporter.id && other.quote.trim());
+  return sentence?.quote ?? disclosureText(row);
+}
+
+function graphReport(data: GraphPayload, target: string): HeadlessBundleResult {
+  const links = new Map(data.links.map(link => [link.id, link]));
+  const nodes = new Map(data.nodes.map(node => [node.id, node]));
+  const route = (path: GraphPath) => ({ ...path, route: pathLabel(path, data), exposureLabel: exposureLabel(path, data),
+    exposure: path.exposure ? { ...path.exposure, denominatorEntity: nodes.get(path.exposure.denominatorEntityId) } : null,
+    evidence: path.linkIds.map((id, index) => ({ hop: index + 1, linkId: id, from: nodes.get(path.nodeIds[index]!),
+      to: nodes.get(path.nodeIds[index + 1]!), primaryEvidenceId: links.get(id)!.primaryEvidenceId, disclosures: links.get(id)!.evidence })),
+  });
+  const sections: HeadlessBundleResult["sections"] = target
+    ? [{ title: `Routes to ${data.target?.name ?? target}`, columns: pathColumns, rows: data.paths.map(route) }]
+    : (["upstream", "downstream", "related"] as const).map(direction => ({
+      title: direction === "upstream" ? "Upstream suppliers" : direction === "downstream" ? "Downstream customers" : "Related companies",
+      columns: [{ key: "company", header: "Company" }, { key: "ticker", header: "Ticker" }, ...pathColumns],
+      rows: data[direction].map(reach => ({ ...route(data.options.ranking === "shortest" ? reach.shortestPath : reach.bestPath), entityId: reach.entityId, company: nodes.get(reach.entityId)?.name,
+        ticker: nodes.get(reach.entityId) ? entityTicker(nodes.get(reach.entityId)!) : null, direction: reach.direction, bestPath: route(reach.bestPath), shortestPath: route(reach.shortestPath) })),
+    }));
+  sections.push({ title: "Disclosure evidence", columns: [
+    { key: "reporter", header: "Reporting company" }, { key: "from", header: "Supplier / from" }, { key: "to", header: "Customer / to" },
+    { key: "role", header: "Role" }, { key: "pct", header: "% disclosed" }, { key: "denominator", header: "Denominator" },
+    { key: "period", header: "Period", textFormat: (value, row) => periodText({ period: String(value), periodMonths: row.periodMonths as number | null }) },
+    { key: "filed", header: "Filed" }, { key: "confidence", header: "Confidence" },
+    // A tagged XBRL fact prints the link's filing sentence when one names the same pair, otherwise the fact in words; exports keep the stored text.
+    { key: "quote", header: "Quote", textFormat: (value, row) => row.statement == null ? String(value ?? "") : String(row.statement) }, { key: "filingUrl", header: "Filing" },
+  ], rows: data.links.flatMap(link => link.evidence.map(item => ({ id: item.id, linkId: link.id, primary: item.id === link.primaryEvidenceId,
+    statement: graphStatement(item, link.evidence),
+    reporter: item.reporter.name, from: item.from.name, to: item.to.name, role: item.role, pct: item.pctOfRevenue ?? null,
+    denominator: item.pctBasis && !(item.sourceKind === "xbrl" && item.pctScope) ? `${item.reporter.name} ${item.pctBasis}${item.pctScope ? ` (${item.pctScope})` : ""}` : null,
+    pctBasis: item.pctBasis, pctScope: item.pctScope, period: item.period, periodMonths: item.periodMonths ?? null, filed: item.filedDate, asOf: item.asOf,
+    confidence: item.confidence, quote: item.quote, quoteLanguage: item.quoteLanguage, quoteGloss: item.quoteGloss ?? null,
+    quoteGlossKind: item.quoteGloss ? "machine_translation" : null, nativeAmount: item.nativeAmount ?? null,
+    nativeCurrency: item.nativeCurrency ?? null, nativeScale: item.nativeScale ?? null, jurisdiction: item.jurisdiction,
+    entityScope: item.entityScope ?? null, sectionRef: item.sectionRef ?? null, sourceAttribution: item.sourceAttribution ?? null,
+    filingUrl: item.filingUrl, evidence: item,
+  }))) });
+  const errors = data.search.reasons.map(reason => `Graph search incomplete: ${reason.replaceAll("_", " ")}`);
+  if (data.access === "preview") errors.push("Gloom Pro is required for full graph depth and results");
+  if (!data.entity) errors.push("The focus company could not be resolved");
+  if (target && !data.target) errors.push("The target company could not be resolved");
+  if (data.truncated && !errors.length) errors.push("Graph results are truncated");
+  return { sections, complete: data.access === "full" && !!data.entity && (!target || !!data.target) && data.search.complete && !data.truncated && data.requestedDepth <= data.maxDepth,
+    errors, metadata: { symbol: data.symbol, target: data.target, asOf: data.asOf, snapshotAt: data.snapshotAt,
+      access: data.access, requestedDepth: data.requestedDepth, maxDepth: data.maxDepth, options: data.options,
+      search: data.search, truncated: data.truncated, methodology: data.methodology, graph: data } };
+}
+
+export const supplyChainHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  freshness: { source: "Company filings, calls and news", status: "not-a-feed", basis: "disclosed relationships" },
+  argument: { kind: "ticker", description: "Company ticker, exchange-qualified ticker, or id:<entity-id>.", placeholder: "ticker" },
+  discovery: { aliases: ["SPLC", "SUPPLY"], dataRequirements: ["Gloom Cloud relationship evidence (Pro with free preview)"],
+    limitations: ["Filings, company announcements, earnings calls and news where evidence is available globally.", "Japan filings await an API key and Taiwan report ingestion is disabled.", "English glosses are machine translations, separate from original evidence.", "Absence is not proof of no relationship.",
+      "Table/Flow free preview: three relationships per role in each direction.", "Pro: up to four hops; free graph preview: one hop and three results per section.", "Reverse percentages belong to the reporting company.",
+      "Path rank scores are not probabilities; chained percentages are estimates.", "Search limits and incomplete reasons accompany every graph report.",
+      "Unconfirmed leads are opt-in and excluded from flow and disclosed values.", "Restricted publisher articles expose links only.",
+      "Table and Flow evidence tiers differ from Graph and Path evidence tiers."] },
+  options: [
+    // No default: left out, the report prints both views; the pane opens on what the company says.
+    { key: "view", type: "enum", settingKey: "view", values: [{ value: "says" }, { value: "names" }], description: "Statements by the company, or other sources naming it; both when left out." },
+    { key: "tab", type: "enum", settingKey: "tab", defaultValue: "table", values: ["table", "flow", "graph", "path"].map(value => ({ value })), description: "Disclosures table, direct flow, multi-hop graph or routes to a target." },
+    { key: "route", type: "integer", minimum: 1, maximum: 50, defaultValue: 1, settingKey: "route", description: "Selected route for graph and evidence screenshots." },
+    { key: "evidence", type: "boolean", settingKey: "evidence", defaultValue: false, description: "Open selected relationship or path evidence in screenshots." },
+    { key: "depth", type: "integer", settingKey: "depth", minimum: 1, maximum: 4, defaultValue: 2, description: "Maximum graph depth in hops (Pro)." },
+    { key: "direction", type: "enum", settingKey: "direction", defaultValue: "both", values: ["upstream", "downstream", "both"].map(value => ({ value })), description: "Follow upstream suppliers, downstream customers, or both." },
+    { key: "roles", type: "string", settingKey: "roles", description: "Comma-separated customer,supplier,partner,competitor,investee roles." },
+    { key: "sources", type: "string", settingKey: "sources", description: "Comma-separated xbrl,filing_text,press_release,call,news,web,import source kinds." },
+    { key: "tiers", type: "string", settingKey: "tiers", description: "Table/Flow: sec (regulatory filings),company,call,reported,unconfirmed (default sec,company,call; unconfirmed opts into leads). Graph/Path: structured,primary,secondary,imported (default all)." },
+    { key: "min-pct", type: "string", settingKey: "minPct", defaultValue: "0", description: "Minimum disclosed percentage, 0 to 100; positive thresholds exclude unknown percentages." },
+    { key: "min-confidence", type: "string", settingKey: "minConfidence", defaultValue: "0", description: "Minimum edge confidence, 0 to 1." },
+    { key: "limit", type: "integer", settingKey: "limit", minimum: 1, maximum: 50, defaultValue: 50, description: "Maximum results per graph section or paths." },
+    { key: "ranking", type: "enum", settingKey: "ranking", defaultValue: "score", values: [{ value: "score" }, { value: "shortest" }], description: "Rank paths by edge-weight product or fewest hops." },
+    { key: "as-of", type: "string", settingKey: "asOf", placeholder: "date", description: `Include disclosures known by this date, as ${DATE_OPTION_EXAMPLES}.`, normalize: (value) => isoDateOption(value, "as-of") },
+    { key: "to", type: "string", settingKey: "to", description: "Target company ticker or id:<entity-id>; required for Path." },
+  ],
+  describe: (args) => `Supply chain | ${args.symbols[0]}${args.options.to ? ` → ${args.options.to}` : ""}`,
+  async load(args, ctx) {
+    if (args.options.tab === "graph" || args.options.tab === "path") {
+      const target = String(args.options.to ?? "").trim();
+      if (args.options.tab === "path" && !target) throw new Error("Path requires a target company: --to TICKER");
+      return graphReport(await fetchSupplyGraph(args.symbols[0]!, graphOptions(args.options), target, ctx.apiClient), target);
+    }
+    const options = supplyOptions(args.options.tiers);
+    const data = await fetchSupplyChain(args.symbols[0]!, ctx.apiClient, options);
+    const sources = new Map<HeadlessPaneRow, SupplyRow>();
+    const sourced = (source: SupplyRow, row: HeadlessPaneRow) => { sources.set(row, source); return row; };
+    // The pane's figures, per tab: Table shows one direction, Flow both.
+    const figures = (key: "counterparties" | "locked") => Object.fromEntries(([["says", ["says"]], ["names", ["names"]], ["flow", ["says", "names"]]] as const)
+      .map(([scope, views]) => [scope, Object.fromEntries(supplyRoleCounts(data, views, options).filter((entry) => entry[key] > 0).map((entry) => [entry.role, entry[key]]))]));
+    const record = (row: SupplyRow) => sourced(row, { counterparty: row.counterparty.name, ticker: entityTicker(row.counterparty), aggregate: row.counterparty.aggregate, role: row.role, direction: row.direction,
+      pct: row.pctOfRevenue, pctBasis: row.pctBasis, pctScope: row.pctScope, usd: row.usd, usdBasis: row.usdBasis, period: row.period, periodMonths: row.periodMonths ?? null, fiscalYear: row.fiscalYear,
+      nativeAmount: row.nativeAmount ?? null, nativeCurrency: row.nativeCurrency ?? null, nativeScale: row.nativeScale ?? null,
+      jurisdiction: row.jurisdiction ?? null, entityScope: row.entityScope ?? null,
+      evidenceTier: evidenceLabel(row), tier: trustTier(row), claimType: row.claimType, corroboration: row.corroboration ?? 1,
+      leadStatus: row.leadStatus ?? "none", whyUnconfirmed: row.whyUnconfirmed ?? null,
+      firstSeenAt: row.firstSeenAt, lastSeenAt: row.lastSeenAt, lastConfirmedAt: row.lastConfirmedAt,
+      source: row.sourceKind, filed: row.filedDate, confidence: row.confidence, reportingCompany: row.reportingEntity.name,
+      quote: row.quote, quoteLanguage: row.quoteLanguage, quoteGloss: row.quoteGloss ?? null, quoteGlossKind: row.quoteGloss ? "machine_translation" : null,
+      quoteMatchMode: row.quoteMatchMode, sourceUrl: row.filingUrl, filingUrl: row.filingUrl, sectionRef: row.sectionRef ?? null, sourceAttribution: row.sourceAttribution ?? null,
+      evidence: row.evidence ?? [] });
+    // --view prints that view alone and says when it is empty; left out, both views print, each only when it has rows.
+    const requested: "says" | "names" | null = args.options.view === "says" || args.options.view === "names" ? args.options.view : null;
+    const views: ("says" | "names")[] = requested ? [requested] : ["says", "names"];
+    const viewTitle = (view: "says" | "names") => view === "says" ? `${data.symbol} says` : `Names ${data.symbol}`;
+    const sections = views.flatMap((view): HeadlessBundleSection[] => {
+      const shown = (rows: SupplyRow[]) => rows.filter((row) => matchesSupplyOptions(row, options));
+      const parts = [
+        { title: viewTitle(view), rows: shown(data[view]).filter((row) => !isUnconfirmed(row)).map(record) },
+        { title: `${viewTitle(view)} | Unconfirmed`, rows: shown(data[view]).filter(isUnconfirmed).map(record) },
+        // Shares from before the reporter's latest period on the same basis: each dated by its own period, never current.
+        { title: `${viewTitle(view)} | Earlier periods`, rows: shown(earlierRows(data, view)).map(record) },
+      ].filter((section) => section.rows.length > 0).map((section) => ({ ...section, columns: tableColumns(section.rows, sources, data.entity?.id) }));
+      if (parts.length || !requested) return parts;
+      // "In the free preview" only when this view holds rows the preview leaves out.
+      const scope = lockedDisclosures(data, [view]) > 0 ? " in the free preview" : "";
+      return [{ title: viewTitle(view), rows: [], empty: view === "names"
+        ? `No other company's disclosures name ${data.symbol}${scope}.`
+        : `${data.symbol}'s own disclosures name no relationship${scope}.` }];
+    });
+    // A requested view is complete when the preview leaves none of its own rows out.
+    const locked = lockedDisclosures(data, views);
+    const truncated = data.truncated && (!requested || locked > 0);
+    return { complete: !truncated, errors: truncated ? [data.access === "preview" ? supplyPreviewNote(data, locked) : "Additional relationships need Gloom Pro"] : [],
+      sections,
+      metadata: { symbol: data.symbol, asOf: data.asOf, view: requested ?? "both", counterparties: figures("counterparties"), locked: figures("locked"),
+        counts: data.counts, earlierCounts: data.earlierCounts ?? null, tierCounts: data.tierCounts, tiers: options.tiers, disclaimer: data.disclaimer } };
+  },
+};