@gloom-sh/terminal 0.0.0-stage → 0.18.5

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

@@ -0,0 +1,366 @@
+import type { ChartVectorShape } from "../../../ui/host";
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { SupplyRole, SupplyRow } from "../../../api-client/supply-chain";
+import { Box, ChartSurface, Span, Text, TextAttributes, useUiCapabilities } from "../../../ui";
+import { useShortcut } from "../../../react/input";
+import { isPlainKey } from "../../../utils/keyboard";
+import { displayWidth } from "../../../utils/format";
+import { BADGE_TINT, ClippedText, NATIVE_BADGE_STYLE } from "../../../components/ui/display";
+import { cardSurfaceStyle } from "../../../components/ui/card";
+import { TOOLTIP_SURFACE_STYLE } from "../../../components/ui/frame";
+import { blendHex } from "../../../theme/colors";
+import { useThemeColors } from "../../../theme/theme-context";
+import { useStaticChartBitmapSize } from "../../../components/chart/composite/bitmap";
+import { fillOpaque, fillRect, parseHex } from "../../../components/chart/native/raster/primitives";
+import { counterpartyKind, counterpartyLabel, disclosedValue, dollars, nativeValue, periodText, roleLabel, ROLE_COLORS, scopeWords, shareParts, fitShareBasis, type FlowBand, type ShareParts } from "./model";
+import { entityTicker } from "./graph-model";
+import { flowChipLabel, flowGeometry, RELATED_LABEL_CELLS, ribbonY, type FlowRibbon, type PositionedNode } from "./flow-layout";
+import { evidenceDate, evidenceLabel, trustTier } from "./trust";
+
+const RIBBON_STEPS = 48;
+const reportedRow = (row: SupplyRow) => trustTier(row) === 4 || trustTier(row) === 5;
+const dashVisible = (t: number) => (Math.max(0, Math.min(1, t)) * RIBBON_STEPS) % 6 <= 4;
+const ROLE_PLURAL: Record<SupplyRole, string> = { supplier: "Suppliers", customer: "Customers", partner: "Partners", competitor: "Competitors", investee: "Investees" };
+
+/** A ribbon's outline in the overlay's 0..1 space: the upper edge out, the lower edge back. */
+function ribbonPolygon(ribbon: FlowRibbon, width: number, height: number, thickness: number) {
+  const xs = Array.from({ length: RIBBON_STEPS + 1 }, (_, i) => ribbon.x0 + (ribbon.x1 - ribbon.x0) * i / RIBBON_STEPS);
+  const upper = xs.map((x) => ({ x: x / width, y: (ribbonY(ribbon, x) - thickness / 2) / height }));
+  const lower = xs.map((x) => ({ x: x / width, y: (ribbonY(ribbon, x) + thickness / 2) / height })).reverse();
+  return [...upper, ...lower];
+}
+
+/** A share and what it is a share of, the basis in the longest form that fits `cells`. */
+function shareText(share: ShareParts, cells: number): string {
+  return `${share.value} ${fitShareBasis(share, cells - displayWidth(share.value) - 1)}`;
+}
+
+/** The disclosed figure a card shows under the name, in the reporting company's own terms, in `cells` cells. */
+function nodeMetric(node: PositionedNode, focusId: string | undefined, cells: number): string {
+  const row = node.row!;
+  if (trustTier(row) !== 1) return `${evidenceLabel(row)} · ${evidenceDate(row)}`;
+  if (node.weight !== null && node.weightBasis === "usd") return dollars(row);
+  const share = shareParts(row, focusId);
+  if (share) return shareText(share, cells);
+  if (nativeValue(row) !== null || row.usd !== null) return disclosedValue(row);
+  // With no figure, the card says where the relationship is disclosed.
+  const reporter = focusId && row.reportingEntity.id !== focusId ? `${entityTicker(row.reportingEntity) ?? row.reportingEntity.name} ` : "";
+  return `${evidenceLabel(row)} · ${reporter}${row.form ?? "filing"}${row.fiscalYear ? ` · FY${row.fiscalYear}` : ""}`;
+}
+
+const GROUP_SEPARATOR = "  ·  ";
+/**
+ * The cohort groups and their shares on one line of `cells`. A group shows
+ * whole or is left to the table behind "+N more", so no share stands cut off
+ * from what it is a share of: the first is always shown, cut to the line if it
+ * must be, the others keep a whole form of their basis.
+ */
+function groupsText(groups: readonly SupplyRow[], focusId: string | undefined, cells: number): string {
+  const entries: string[] = [];
+  for (const [index, row] of groups.entries()) {
+    const share = shareParts(row, focusId);
+    const label = counterpartyLabel(row);
+    const rest = groups.length - index - 1;
+    const room = cells - displayWidth(entries.join(GROUP_SEPARATOR)) - (entries.length ? displayWidth(GROUP_SEPARATOR) : 0) - (rest ? displayWidth(`${GROUP_SEPARATOR}+${rest} more`) : 0);
+    const basisRoom = room - displayWidth(label) - displayWidth(share?.value ?? "") - 2;
+    if (entries.length && (share ? !share.forms.some((form) => displayWidth(form) <= basisRoom) : displayWidth(label) > room)) break;
+    entries.push(share ? `${label} ${shareText(share, room - displayWidth(label) - 1)}` : label);
+  }
+  const more = groups.length - entries.length;
+  return `${entries.join(GROUP_SEPARATOR)}${more > 0 ? `${GROUP_SEPARATOR}+${more} more` : ""}`;
+}
+
+/**
+ * Suppliers flow in from the left and customers out to the right of the
+ * focus company. Ribbon width follows a disclosed share or dollar figure on
+ * one comparable scale per column; a relationship without one is a hairline.
+ * Hover or select a ribbon or card to bring it forward; click to open the
+ * counterparty. The desktop draws SVG ribbons and real cards; the terminal
+ * draws the same geometry in braille with aligned text.
+ */
+export function SupplyFlow({ rows, symbol, focusName, focusId, width, height, focused, selectedId, onSelect, onOpen, onVisible }: {
+  rows: SupplyRow[]; symbol: string; focusName?: string | null; focusId?: string; width: number; height: number; focused: boolean;
+  selectedId: string | null; onSelect: (id: string) => void; onOpen: (row: SupplyRow) => void; onVisible: (ids: string[]) => void;
+}) {
+  const colors = useThemeColors();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const bitmapSize = useStaticChartBitmapSize(width, height);
+  const [pages, setPages] = useState<Partial<Record<FlowBand, number>>>({});
+  const [relatedPages, setRelatedPages] = useState<Partial<Record<SupplyRole, number>>>({});
+  const [hovered, setHovered] = useState<string | null>(null);
+  const surfaceRef = useRef<{ x: number; y: number; absoluteX?: number; absoluteY?: number } | null>(null);
+  const focusLabel = focusName && displayWidth(focusName) <= 22 ? focusName : symbol;
+  const geometry = useMemo(() => flowGeometry(rows, { width, height, focusId, focusLabelWidth: Math.max(symbol.length, displayWidth(focusLabel)), pages, relatedPages }),
+    [rows, width, height, focusId, symbol, focusLabel, pages, relatedPages]);
+  const { nodes, ribbons, center } = geometry;
+  const reportedIds = useMemo(() => new Set(nodes.filter((node) => node.row && reportedRow(node.row)).map((node) => node.id)), [nodes]);
+  const visibleIds = nodes.filter((node) => node.row).map((node) => node.id).join("\n");
+  useEffect(() => { onVisible(visibleIds ? visibleIds.split("\n") : []); }, [visibleIds, onVisible]);
+  const selectedIndex = Math.max(0, nodes.findIndex((node) => node.id === selectedId));
+  const selected = nodes[selectedIndex]?.id ?? null;
+  const active = hovered ?? selected;
+  const focusTint = blendHex(colors.bg, colors.textBright, 0.55);
+  const selectNode = (node: PositionedNode) => {
+    if (node.more && node.band === "related" && node.role) setRelatedPages((old) => ({ ...old, [node.role!]: (old[node.role!] ?? 0) + 1 }));
+    else if (node.more) setPages((old) => ({ ...old, [node.band]: (old[node.band] ?? 0) + 1 }));
+    else if (node.row) { onSelect(node.id); onOpen(node.row); }
+  };
+  useShortcut((event) => {
+    if (!focused || event.defaultPrevented || nodes.length === 0) return;
+    if (isPlainKey(event, "j", "down") || isPlainKey(event, "k", "up")) {
+      const direction = isPlainKey(event, "j", "down") ? 1 : -1;
+      onSelect(nodes[(selectedIndex + direction + nodes.length) % nodes.length]!.id);
+    } else if (isPlainKey(event, "return", "enter")) selectNode(nodes[selectedIndex]!);
+    else return;
+    event.preventDefault(); event.stopPropagation();
+  });
+
+  const ribbonColors = (ribbon: FlowRibbon) => ribbon.band === "suppliers" ? [ROLE_COLORS[ribbon.role], focusTint] : [focusTint, ROLE_COLORS[ribbon.role]];
+  const vectors = useMemo<ChartVectorShape[]>(() => ribbons.flatMap((ribbon): ChartVectorShape[] => {
+    const lit = active === ribbon.id;
+    const dim = hovered !== null && !lit;
+    if (ribbon.thickness === null) {
+      const vector: ChartVectorShape = { id: ribbon.id, points: Array.from({ length: RIBBON_STEPS + 1 }, (_, i) => {
+        const x = ribbon.x0 + (ribbon.x1 - ribbon.x0) * i / RIBBON_STEPS;
+        return { x: x / width, y: ribbonY(ribbon, x) / height };
+      }), color: ROLE_COLORS[ribbon.role], gradient: ribbonColors(ribbon), strokeWidth: lit ? 2.4 : 1.4, opacity: dim ? 0.25 : lit ? 1 : 0.7 };
+      if (!reportedIds.has(ribbon.id)) return [vector];
+      // Use the same gaps in SVG, bitmap and braille; reported links are always hairlines.
+      const [from, to] = ribbonColors(ribbon);
+      return Array.from({ length: 8 }, (_, index) => ({ ...vector, id: `${ribbon.id}:dash:${index}`,
+        points: vector.points.slice(index * 6, index * 6 + 5),
+        gradient: [blendHex(from!, to!, index * 6 / RIBBON_STEPS), blendHex(from!, to!, (index * 6 + 4) / RIBBON_STEPS)] }));
+    }
+    return [{ id: ribbon.id, points: ribbonPolygon(ribbon, width, height, ribbon.thickness), color: ROLE_COLORS[ribbon.role], fill: true,
+      gradient: ribbonColors(ribbon), fillOpacity: lit ? 0.9 : 0.6, opacity: dim ? 0.3 : 1 }];
+  }), [ribbons, reportedIds, active, hovered, width, height, focusTint]);
+
+  // The terminal's native graphics: the same ribbons filled column by column.
+  const bitmap = useMemo(() => {
+    if (desktop || !bitmapSize) return null;
+    const { pixelWidth: w, pixelHeight: h } = bitmapSize;
+    const sx = w / width, sy = h / height;
+    const pixels = new Uint8Array(w * h * 4); fillOpaque(pixels, parseHex(colors.bg));
+    for (const ribbon of ribbons) {
+      const [from, to] = ribbonColors(ribbon);
+      for (let px = Math.round(ribbon.x0 * sx); px <= Math.round(ribbon.x1 * sx); px++) {
+        const x = px / sx, t = (x - ribbon.x0) / Math.max(1e-6, ribbon.x1 - ribbon.x0);
+        if (reportedIds.has(ribbon.id) && !dashVisible(t)) continue;
+        const half = ribbon.thickness === null ? 0.6 / sy : ribbon.thickness / 2;
+        const y = ribbonY(ribbon, x);
+        fillRect(pixels, w, h, px, (y - half) * sy, px, (y + half) * sy, parseHex(blendHex(from!, to!, t), active === ribbon.id ? 0.95 : 0.7));
+      }
+    }
+    return { width: w, height: h, pixels };
+  }, [desktop, bitmapSize, ribbons, reportedIds, colors.bg, width, height, active, focusTint]);
+
+  // Braille fallback: a filled band per ribbon, coloured along its length from the role to the focus company.
+  const fallback = useMemo(() => {
+    if (desktop || bitmap) return null;
+    const grid = Array.from({ length: height }, () => Array.from({ length: width }, () => ({ mask: 0, color: colors.textDim })));
+    const bits = [[1, 8], [2, 16], [4, 32], [64, 128]];
+    for (const ribbon of ribbons) {
+      const [from, to] = ribbonColors(ribbon);
+      const lit = active === ribbon.id;
+      for (let dx = Math.ceil(ribbon.x0 * 2); dx < Math.floor(ribbon.x1 * 2); dx++) {
+        const x = (dx + 0.5) / 2, t = (x - ribbon.x0) / Math.max(1e-6, ribbon.x1 - ribbon.x0);
+        if (reportedIds.has(ribbon.id) && !dashVisible(t)) continue;
+        const y = ribbonY(ribbon, x);
+        const half = ribbon.thickness === null ? 0 : ribbon.thickness / 2;
+        const color = blendHex(from!, to!, t);
+        for (let dy = Math.round((y - half) * 4 - 0.5); dy <= Math.round((y + half) * 4 - 0.5); dy++) {
+          const cell = grid[Math.floor(dy / 4)]?.[Math.floor(dx / 2)];
+          if (!cell || dy < 0) continue;
+          cell.mask |= bits[dy % 4]![dx % 2]!;
+          cell.color = ribbon.thickness === null && !lit ? blendHex(colors.bg, color, 0.75) : 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, bitmap, width, height, ribbons, reportedIds, colors.textDim, colors.bg, active, focusTint]);
+
+  /** Hovering a ribbon brings it forward; the nearest one under the pointer wins. */
+  const hoverAt = (event: { preciseX?: number; preciseY?: number; x: number; y: number }) => {
+    const origin = surfaceRef.current;
+    if (!origin) return;
+    const x = (event.preciseX ?? event.x) - (origin.absoluteX ?? origin.x), y = (event.preciseY ?? event.y) - (origin.absoluteY ?? origin.y);
+    let best: { id: string; distance: number } | null = null;
+    for (const ribbon of ribbons) {
+      if (x < ribbon.x0 || x > ribbon.x1) continue;
+      const distance = Math.abs(ribbonY(ribbon, x) - y) - (ribbon.thickness ?? 0) / 2;
+      if (distance < 0.6 && (!best || distance < best.distance)) best = { id: ribbon.id, distance };
+    }
+    const next = best?.id ?? null;
+    if (next !== hovered) setHovered(next);
+  };
+
+  const hoveredNode = hovered ? nodes.find((node) => node.id === hovered && node.row) : null;
+  const legend = flowLegend(geometry, symbol);
+  const header = (band: "suppliers" | "customers", x: number) => {
+    const role: SupplyRole = band === "suppliers" ? "supplier" : "customer";
+    return <Box position="absolute" top={geometry.headerRow} left={x} width={geometry.cardWidth}>
+      <Text fg={ROLE_COLORS[role]} attributes={TextAttributes.BOLD}>{band === "suppliers" ? "Suppliers" : "Customers"}</Text>
+    </Box>;
+  };
+  const hasBand = (band: "suppliers" | "customers") => nodes.some((node) => node.band === band);
+  return <Box width={width} height={height} flexGrow={1} flexBasis={0} minHeight={0} position="relative" overflow="hidden">
+    <ChartSurface ref={surfaceRef} width={width} height={height} position="absolute" left={0} top={0}
+      vectors={desktop ? vectors : undefined} bitmap={bitmap} flexDirection="column"
+      onMouseMove={hoverAt} onMouseOut={() => setHovered(null)}
+      onMouseDown={() => { const node = hovered ? nodes.find((entry) => entry.id === hovered) : null; if (node) selectNode(node); }}
+      aria-label={hovered ? flowNodeName(nodes.find((entry) => entry.id === hovered)!) : "Supply chain flow"}>
+      {fallback ? fallback.map((spans, y) => <Text key={y}>{spans.map((span, i) => <Span key={i} fg={span.color}>{span.text}</Span>)}</Text>) : null}
+    </ChartSurface>
+    {header("suppliers", 1)}
+    {header("customers", width - geometry.cardWidth - 1)}
+    {!hasBand("suppliers") ? <Box position="absolute" top={center.y + 1} left={1}><Text fg={colors.textMuted}>None disclosed</Text></Box> : null}
+    {!hasBand("customers") ? <Box position="absolute" top={center.y + 1} left={width - geometry.cardWidth - 1}><Text fg={colors.textMuted}>None disclosed</Text></Box> : null}
+    <FocusCard symbol={symbol} name={focusName ?? null} {...center} desktop={desktop} />
+    {nodes.filter((node) => node.band !== "related").map((node) => <FlowCard key={node.id} node={node} focusId={focusId} desktop={desktop}
+      active={active === node.id} onPress={() => selectNode(node)} onHover={(on) => setHovered(on ? node.id : null)} />)}
+    {geometry.related.map((row) => <Box key={row.role} position="absolute" top={row.y} left={1} width={RELATED_LABEL_CELLS}>
+      <Text fg={ROLE_COLORS[row.role]}>{ROLE_PLURAL[row.role]}</Text>
+    </Box>)}
+    {geometry.related.flatMap((row) => row.chips).map((node) => <FlowChip key={node.id} node={node} desktop={desktop} active={active === node.id}
+      onPress={() => selectNode(node)} onHover={(on) => setHovered(on ? node.id : null)} />)}
+    {geometry.groupRow !== null ? <Box position="absolute" top={geometry.groupRow} left={1} width={width - 2} flexDirection="row" overflow="hidden">
+      <Box width={RELATED_LABEL_CELLS} flexShrink={0}><Text fg={colors.textDim}>Groups</Text></Box>
+      <ClippedText fg={colors.textDim} text={groupsText(geometry.groups, focusId, width - RELATED_LABEL_CELLS - 3)} width={width - RELATED_LABEL_CELLS - 3} />
+    </Box> : null}
+    {legend ? <Box position="absolute" top={geometry.legendRow} left={1} width={width - 2} flexDirection="row" gap={2} overflow="hidden">
+      {legend.map((entry) => <Box key={entry.id} flexDirection="row" gap={1} flexShrink={0}>
+        <LegendSwatch kind={entry.kind} desktop={desktop} />
+        <Text fg={colors.textDim}>{entry.label}</Text>
+      </Box>)}
+    </Box> : null}
+    {hoveredNode && hoveredNode.band !== "related" ? <FlowTooltip node={hoveredNode} focusId={focusId} width={width} desktop={desktop} anchor={tooltipAnchor(hoveredNode, ribbons, width)} /> : null}
+  </Box>;
+}
+
+function flowNodeName(node: PositionedNode): string {
+  if (node.more) return `Show ${node.more} more ${node.role ? ROLE_PLURAL[node.role].toLowerCase() : node.band}`;
+  const name = node.row ? counterpartyLabel(node.row) : node.label;
+  const role = node.role ? roleLabel(node.role) : node.band;
+  return `Open ${name}, ${role}`;
+}
+
+function tooltipAnchor(node: PositionedNode, ribbons: readonly FlowRibbon[], width: number) {
+  const ribbon = ribbons.find((entry) => entry.id === node.id);
+  const x = ribbon ? (ribbon.x0 + ribbon.x1) / 2 : node.x + node.width / 2;
+  const y = ribbon ? ribbonY(ribbon, x) : node.y;
+  return { x: Math.max(1, Math.min(width - 40, Math.round(x - 19))), y: Math.round(y) + 1 };
+}
+
+function flowLegend(geometry: ReturnType<typeof flowGeometry>, symbol: string): { id: string; kind: "weighted" | "hairline" | "reported"; label: string }[] | null {
+  const entries: { id: string; kind: "weighted" | "hairline" | "reported"; label: string }[] = [];
+  const { suppliers, customers, scope } = geometry.scale;
+  if (customers === "revenue") entries.push({ id: "customers", kind: "weighted", label: `customers: share of ${symbol}${scope ? ` ${scopeWords(scope)}` : ""} revenue` });
+  else if (customers === "usd") entries.push({ id: "customers", kind: "weighted", label: "customers: disclosed USD" });
+  if (suppliers === "usd") entries.push({ id: "suppliers", kind: "weighted", label: "suppliers: disclosed USD" });
+  else if (suppliers === "revenue") entries.push({ id: "suppliers", kind: "weighted", label: `suppliers: share of ${symbol} revenue` });
+  const reported = new Set(geometry.nodes.filter((node) => node.row && reportedRow(node.row)).map((node) => node.id));
+  if (geometry.ribbons.some((ribbon) => ribbon.thickness === null && !reported.has(ribbon.id))) entries.push({ id: "hairline", kind: "hairline", label: "no comparable figure" });
+  if (reported.size) entries.push({ id: "reported", kind: "reported", label: "reported" });
+  return entries.length ? entries : null;
+}
+
+function LegendSwatch({ kind, desktop }: { kind: "weighted" | "hairline" | "reported"; desktop: boolean }) {
+  const colors = useThemeColors();
+  if (!desktop) return <Text fg={colors.textMuted}>{kind === "weighted" ? "━━" : kind === "reported" ? "╌╌" : "──"}</Text>;
+  return <Box width={2} height={1} justifyContent="center">
+    <Box style={kind === "reported" ? { height: 0, borderTop: `1px dashed ${colors.textMuted}` } : { height: kind === "weighted" ? "7px" : "1px", borderRadius: kind === "weighted" ? "2px" : 0,
+      background: `linear-gradient(90deg, ${colors.textMuted}, ${colors.textDim})` }} />
+  </Box>;
+}
+
+function FocusCard({ symbol, name, x, y, width, height, desktop }: { symbol: string; name: string | null; x: number; y: number; width: number; height: number; desktop: boolean }) {
+  const colors = useThemeColors();
+  // The terminal's border takes two rows; the name shows only when the symbol keeps its own.
+  const showName = !!name && name.toUpperCase() !== symbol.toUpperCase() && height >= (desktop ? 3 : 4);
+  return <Box position="absolute" left={x} top={y} width={width} height={height} flexDirection="column" alignItems="center" justifyContent="center"
+    border={!desktop} borderStyle="rounded" borderColor={colors.textMuted}
+    style={desktop ? cardSurfaceStyle({ padding: "0" }) : undefined}>
+    <Text fg={colors.textBright} attributes={TextAttributes.BOLD}>{symbol}</Text>
+    {showName ? <ClippedText fg={colors.textDim} text={name!} width={width - 4} /> : null}
+  </Box>;
+}
+
+function FlowCard({ node, focusId, desktop, active, onPress, onHover }: {
+  node: PositionedNode; focusId?: string; desktop: boolean; active: boolean; onPress: () => void; onHover: (on: boolean) => void;
+}) {
+  const colors = useThemeColors();
+  const role = node.role;
+  const accent = role ? ROLE_COLORS[role] : colors.textMuted;
+  const company = node.row ? counterpartyKind(node.row) === "company" : false;
+  const name = node.more ? `+${node.more} more` : node.row ? counterpartyLabel(node.row) : node.label;
+  const ticker = node.row ? entityTicker(node.row.counterparty) : null;
+  const inner = Math.max(4, node.width - (desktop ? 2 : 2));
+  const metric = node.row ? nodeMetric(node, focusId, inner - (desktop ? 0 : 1)) : "";
+  const nameWidth = Math.max(4, inner - (ticker ? displayWidth(ticker) + 1 : 0));
+  const titleColor = node.more ? colors.textDim : company ? colors.textBright : colors.text;
+  return <Box position="absolute" left={node.x} top={node.y} width={node.width} height={node.more ? 1 : node.height} flexDirection="column"
+    backgroundColor={desktop ? undefined : node.more ? undefined : active ? colors.selected : blendHex(colors.bg, accent, 0.12)}
+    // The card, in the relationship's colour; "+N more" is the same card without a fill, its rule dotted.
+    style={desktop ? { ...cardSurfaceStyle({ selected: active, accent, padding: "0 var(--gloom-space-sm)" }),
+      ...(node.more ? { background: "transparent", borderLeftStyle: "dotted" } : {}), cursor: "pointer" } : undefined}
+    onMouseDown={onPress} onMouseOver={() => onHover(true)} onMouseOut={() => onHover(false)} data-gloom-role="supply-flow-node"
+    role="button" aria-label={flowNodeName(node)}>
+    {/* The ticker shows only beside the whole name. On the desktop that is CSS: the row wraps, one line shows, and a ticker that does not fit goes to the hidden line. */}
+    <Box flexDirection="row" height={1} overflow="hidden" style={desktop ? { flexWrap: "wrap" } : undefined}>
+      {!desktop ? <Text fg={node.more ? colors.textMuted : accent}>▍</Text> : null}
+      <ClippedText fg={active && !desktop ? colors.selectedText : titleColor} attributes={company ? TextAttributes.BOLD : 0} text={name} width={nameWidth} />
+      {ticker && (desktop || displayWidth(name) + displayWidth(ticker) + 1 <= inner)
+        ? <Text fg={colors.textDim} style={desktop ? { flex: "0 0 auto" } : undefined}>{` ${ticker}`}</Text> : null}
+    </Box>
+    {metric ? <Box height={1} paddingLeft={desktop ? 0 : 1} overflow="hidden">
+      <ClippedText fg={active && !desktop ? colors.selectedText : colors.textDim} text={metric} width={inner - (desktop ? 0 : 1)} />
+    </Box> : null}
+  </Box>;
+}
+
+function FlowChip({ node, desktop, active, onPress, onHover }: { node: PositionedNode; desktop: boolean; active: boolean; onPress: () => void; onHover: (on: boolean) => void }) {
+  const colors = useThemeColors();
+  const accent = node.role ? ROLE_COLORS[node.role] : colors.textMuted;
+  // Desktop: the one chip (Badge), tinted toward the role, solid when chosen.
+  const background = desktop
+    ? active ? accent : node.more ? undefined : blendHex(colors.bg, accent, BADGE_TINT)
+    : active ? blendHex(colors.bg, accent, 0.45) : node.more ? undefined : blendHex(colors.bg, accent, 0.14);
+  const text = <ClippedText fg={node.more ? colors.textDim : active ? desktop ? colors.bg : colors.textBright : accent} text={flowChipLabel(node)} width={node.width - 2} />;
+  return <Box position="absolute" left={node.x} top={node.y} width={node.width} height={1} justifyContent={desktop ? "center" : undefined}
+    onMouseDown={onPress} onMouseOver={() => onHover(true)} onMouseOut={() => onHover(false)} data-gloom-role="supply-flow-chip"
+    role="button" aria-label={flowNodeName(node)}>
+    {/* The desktop chip leaves a hairline of row above and below, like ticker chips. */}
+    {desktop ? <Box paddingX={1} minWidth={0} backgroundColor={background} justifyContent="center" style={{ ...NATIVE_BADGE_STYLE, cursor: "pointer" }}>{text}</Box>
+      : <Box paddingX={1} height={1} backgroundColor={background}>{text}</Box>}
+  </Box>;
+}
+
+/** What the hovered relationship is: the figure and its denominator, the period and the filing. */
+function FlowTooltip({ node, focusId, width, desktop, anchor }: { node: PositionedNode; focusId?: string; width: number; desktop: boolean; anchor: { x: number; y: number } }) {
+  const colors = useThemeColors();
+  const row = node.row!;
+  const share = shareParts(row, focusId);
+  const lines = [
+    share ? `${share.value} ${share.basis}` : nativeValue(row) !== null || row.usd !== null ? disclosedValue(row) : "No figure disclosed",
+    `${roleLabel(row.role)} · ${periodText(row)}`,
+    trustTier(row) === 1
+      ? `${evidenceLabel(row)} · ${entityTicker(row.reportingEntity) ?? row.reportingEntity.name} ${row.form ?? "filing"}${row.filedDate ? ` filed ${row.filedDate}` : ""}`
+      : `${evidenceLabel(row)} · ${evidenceDate(row)}`,
+  ];
+  const tooltipWidth = Math.min(width - 2, Math.max(28, ...lines.map((line) => displayWidth(line) + 4), displayWidth(counterpartyLabel(row)) + 4));
+  return <Box position="absolute" left={Math.max(1, Math.min(width - tooltipWidth - 1, anchor.x))} top={anchor.y} width={tooltipWidth} height={lines.length + 1}
+    flexDirection="column" paddingX={1} backgroundColor={desktop ? undefined : colors.panel} border={!desktop} borderColor={ROLE_COLORS[row.role]}
+    style={desktop ? { ...TOOLTIP_SURFACE_STYLE, padding: "0 var(--gloom-space-sm)", zIndex: 20 } : undefined}
+    data-gloom-role="supply-flow-tooltip">
+    <ClippedText fg={colors.textBright} attributes={TextAttributes.BOLD} text={counterpartyLabel(row)} width={tooltipWidth - 2} />
+    {lines.map((line, index) => <ClippedText key={index} fg={index === 0 ? colors.text : colors.textDim} text={line} width={tooltipWidth - 2} />)}
+  </Box>;
+}

package/src/plugins/builtin/supply-chain/graph-client.ts

@@ -0,0 +1,86 @@
+import { apiClient } from "../../../api-client";
+import { DEFAULT_GRAPH_OPTIONS, supplyGraphQuery, type GraphOptions, type GraphPayload, type GraphPath } from "../../../api-client/supply-chain-graph";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { dateOptionError, readCalendarDate } from "../../../utils/calendar-date";
+import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+import { normalizeSupplyRow, validPeriodMonths, validSupplyEntity, validSupplyRow } from "./client";
+import { graphEvidenceRow } from "./graph-evidence";
+import { activeRelationship, isUnconfirmed } from "./trust";
+
+export const graphCache = createPluginCache<GraphPayload>({ kind: "supply-graph", source: "gloom-cloud", schemaVersion: 2, policy: { staleMs: 300_000, expireMs: 86_400_000 } });
+const unit = (x: unknown): x is number => typeof x === "number" && Number.isFinite(x) && x >= 0 && x <= 1;
+const id = (x: unknown): x is string => typeof x === "string" && x.length > 0;
+export function validateGraph(data: GraphPayload): GraphPayload {
+  try {
+    if (!data || !id(data.symbol) || !["available", "unavailable"].includes(data.status) || !["full", "preview"].includes(data.access)
+      || !Array.isArray(data.nodes) || !data.nodes.every(validSupplyEntity) || !Array.isArray(data.links)
+      || typeof data.truncated !== "boolean" || typeof data.search?.complete !== "boolean" || !Array.isArray(data.search.reasons)
+      || !data.search.reasons.every(id) || !Number.isFinite(Date.parse(data.snapshotAt))) throw 0;
+    const nodes = new Set(data.nodes.map(node => node.id));
+    const links = new Map(data.links.map(link => [link.id, link]));
+    if (nodes.size !== data.nodes.length || links.size !== data.links.length || (data.entity && !nodes.has(data.entity.id))
+      || (data.target && !validSupplyEntity(data.target))) throw 0;
+    for (const link of data.links) {
+      if (!id(link.id) || !nodes.has(link.from) || !nodes.has(link.to) || !unit(link.confidence) || !unit(link.weight)
+        || !["commerce", "partner", "competitor", "investee"].includes(link.relationship) || !Array.isArray(link.evidence)
+        || !link.evidence.some(item => item.id === link.primaryEvidenceId)) throw 0;
+      for (const item of link.evidence) {
+        const row = graphEvidenceRow(item);
+        if (!validSupplyRow(row) || !activeRelationship(row) || isUnconfirmed(row)
+          || !validSupplyEntity(item.from) || !validSupplyEntity(item.to)
+          || !["structured", "primary", "secondary", "imported"].includes(item.tier)) throw 0;
+      }
+    }
+    const path = (entry: GraphPath) => {
+      if (!id(entry.id) || !Number.isInteger(entry.hops) || entry.hops < 1 || entry.hops > 4 || !unit(entry.score) || !unit(entry.confidence)
+        || entry.linkIds.length !== entry.hops || entry.nodeIds.length !== entry.hops + 1 || new Set(entry.nodeIds).size !== entry.nodeIds.length
+        || !entry.nodeIds.every(node => nodes.has(node))) throw 0;
+      entry.linkIds.forEach((key, index) => {
+        const link = links.get(key), a = entry.nodeIds[index], b = entry.nodeIds[index + 1];
+        if (!link || !(link.from === a && link.to === b || link.to === a && link.from === b)) throw 0;
+      });
+      if (entry.exposure && (entry.linkIds.some(id => graphEvidenceRow(links.get(id)!.evidence.find(item => item.id === links.get(id)!.primaryEvidenceId)!).tier !== 1) || entry.exposure.estimated !== true || !Number.isFinite(entry.exposure.pct) || entry.exposure.pct < 0 || entry.exposure.pct > 100
+        || !entry.nodeIds.includes(entry.exposure.denominatorEntityId) || !["revenue", "receivables", "cost", "purchases"].includes(entry.exposure.basis) || !validPeriodMonths(entry.exposure.periodMonths))) throw 0;
+    };
+    data.paths.forEach(path);
+    for (const entry of [...data.upstream, ...data.downstream, ...data.related]) {
+      if (!nodes.has(entry.entityId)) throw 0;
+      path(entry.bestPath); path(entry.shortestPath);
+    }
+    const o = data.options;
+    if (!Number.isInteger(o.depth) || o.depth < 1 || o.depth > 4 || !["both", "upstream", "downstream"].includes(o.direction)
+      || !unit(o.minConfidence) || !Number.isFinite(o.minPct) || o.minPct < 0 || o.minPct > 100 || !Number.isInteger(o.limit) || o.limit < 1 || o.limit > 50
+      || !["score", "shortest"].includes(o.ranking) || ![o.roles, o.sources, o.tiers].every(Array.isArray)) throw 0;
+    return { ...data, links: data.links.map(link => ({ ...link, evidence: link.evidence.map(item => {
+      const row = normalizeSupplyRow(graphEvidenceRow(item));
+      return { ...item, trustTier: row.tier, quote: row.quote, quoteLanguage: row.quoteLanguage, quoteGloss: row.quoteGloss,
+        pctOfRevenue: row.pctOfRevenue, pctBasis: row.pctBasis, pctScope: row.pctScope,
+        usd: row.usd, usdBasis: row.usdBasis, nativeAmount: row.nativeAmount, nativeCurrency: row.nativeCurrency, nativeScale: row.nativeScale,
+        lastConfirmedAt: row.lastConfirmedAt, evidence: row.evidence };
+    }) })) };
+  } catch { throw new Error("The server returned an unreadable supply chain graph"); }
+}
+export async function fetchSupplyGraph(symbol: string, options: Partial<GraphOptions> = {}, target = "", client: Pick<typeof apiClient, "getCloudSupplyGraph" | "getCloudSupplyPaths"> = apiClient) {
+  try { return validateGraph(await (target ? client.getCloudSupplyPaths(symbol, target, options) : client.getCloudSupplyGraph(symbol, options))); }
+  catch (error) { throw unavailableOnServer(error, "Supply chain graph is not available yet.", [404, 503]); }
+}
+const key = (symbol: string, target: string, options: GraphOptions, access: string) => `${access}:${symbol.toUpperCase()}:${target.toUpperCase()}:${supplyGraphQuery(options)}`;
+export const cachedGraph = (symbol: string, target: string, options: GraphOptions, access: string) => cachedCloudResource(graphCache, key(symbol, target, options, access), validateGraph);
+export const loadGraph = (symbol: string, target: string, options: GraphOptions, access: string, force = false) => loadCloudResource(graphCache, key(symbol, target, options, access), () => fetchSupplyGraph(symbol, options, target), { force, validate: validateGraph });
+export function graphOptions(input: Record<string, unknown>): GraphOptions {
+  const asOfText = String(input.asOf || input["as-of"] || "").trim();
+  const asOf = asOfText ? readCalendarDate(asOfText) : null;
+  if (asOfText && !asOf) throw new Error(dateOptionError(asOfText, "", { subject: "a filing cutoff" }));
+  const csv = (key: string) => String(input[key] ?? "").split(",").filter(Boolean);
+  const options = { ...DEFAULT_GRAPH_OPTIONS, depth: Number(input.depth ?? 2), direction: String(input.direction ?? "both") as GraphOptions["direction"],
+    roles: csv("roles") as GraphOptions["roles"], sources: csv("sources") as GraphOptions["sources"], tiers: csv("tiers") as GraphOptions["tiers"],
+    minPct: Number(input.minPct ?? input["min-pct"] ?? 0), minConfidence: Number(input.minConfidence ?? input["min-confidence"] ?? 0), limit: Number(input.limit ?? 50),
+    ranking: String(input.ranking ?? "score") as GraphOptions["ranking"], ...(asOf ? { asOf } : {}) };
+  if (!Number.isInteger(options.depth) || options.depth < 1 || options.depth > 4 || !["both", "upstream", "downstream"].includes(options.direction)
+    || !Number.isInteger(options.limit) || options.limit < 1 || options.limit > 50 || !["score", "shortest"].includes(options.ranking)
+    || !unit(options.minConfidence) || !Number.isFinite(options.minPct) || options.minPct < 0 || options.minPct > 100
+    || options.roles.some(value => !["customer", "supplier", "partner", "competitor", "investee"].includes(value))
+    || options.sources.some(value => !["xbrl", "filing_text", "call", "news", "web", "import", "press_release"].includes(value))
+    || options.tiers.some(value => !["structured", "primary", "secondary", "imported"].includes(value))) throw new Error("Invalid supply chain graph filters");
+  return options;
+}

package/src/plugins/builtin/supply-chain/graph-evidence.ts

@@ -0,0 +1,25 @@
+import type { SupplyRow } from "../../../api-client/supply-chain";
+import type { GraphEvidence } from "../../../api-client/supply-chain-graph";
+
+/** Graph classes describe extraction format; source trust is a separate numeric tier. */
+export function graphEvidenceRow(evidence: GraphEvidence): SupplyRow {
+  return {
+    id: evidence.id, counterparty: evidence.reporter.id === evidence.to.id ? evidence.from : evidence.to,
+    reportingEntity: evidence.reporter, role: evidence.role,
+    direction: evidence.role === "supplier" ? "in" : evidence.role === "customer" ? "out" : "mutual",
+    sourceKind: evidence.sourceKind, period: evidence.period, periodMonths: evidence.periodMonths ?? null, asOf: evidence.asOf,
+    fiscalYear: evidence.fiscalYear ?? null, form: evidence.form ?? null, filedDate: evidence.filedDate ?? null,
+    pctOfRevenue: evidence.pctOfRevenue ?? null, pctBasis: evidence.pctBasis ?? null, pctScope: evidence.pctScope ?? null,
+    usd: evidence.usd ?? null, usdBasis: evidence.usdBasis ?? null,
+    nativeAmount: evidence.nativeAmount ?? null, nativeCurrency: evidence.nativeCurrency ?? null, nativeScale: evidence.nativeScale ?? null,
+    jurisdiction: evidence.jurisdiction, entityScope: evidence.entityScope,
+    confidence: evidence.confidence, quote: evidence.quote, quoteLanguage: evidence.quoteLanguage ?? null,
+    quoteGloss: evidence.quoteGloss, sectionRef: evidence.sectionRef, sourceAttribution: evidence.sourceAttribution,
+    quoteMatchMode: evidence.quoteMatchMode ?? null, filingUrl: evidence.filingUrl, accession: evidence.accession ?? null,
+    tier: evidence.trustTier ?? (evidence.sourceKind === "xbrl" || evidence.sourceKind === "filing_text" ? 1
+      : evidence.sourceKind === "press_release" ? 2 : evidence.sourceKind === "call" ? 3 : 4),
+    claimType: evidence.claimType, corroboration: evidence.corroboration, leadStatus: evidence.leadStatus,
+    firstSeenAt: evidence.firstSeenAt, lastSeenAt: evidence.lastSeenAt, lastConfirmedAt: evidence.lastConfirmedAt,
+    whyUnconfirmed: evidence.whyUnconfirmed, evidence: evidence.evidence,
+  };
+}

package/src/plugins/builtin/supply-chain/graph-model.ts

@@ -0,0 +1,53 @@
+import type { SupplyEntity } from "../../../api-client/supply-chain";
+import type { GraphPath, GraphPayload } from "../../../api-client/supply-chain-graph";
+import { getListingSymbol } from "../../../sources/listing-symbols";
+import { isUsListingExchange, publicTickerKey } from "../../../utils/exchanges";
+
+export const entityKey = (entity: SupplyEntity) => entity.ticker ? publicTickerKey(entity.ticker, entity.exchange ?? undefined) : `id:${entity.id}`;
+/**
+ * The ticker as shown and typed to open it: a US listing bare, any other with
+ * its venue's suffix, so Standard Chartered reads STAN.L and never a bare STAN
+ * that a US company could hold.
+ */
+export const entityTicker = (entity: Pick<SupplyEntity, "ticker" | "exchange">) =>
+  entity.ticker && entity.exchange && !isUsListingExchange(entity.exchange) ? getListingSymbol(entity.ticker, entity.exchange) : entity.ticker;
+export const entityLabel = (entity: SupplyEntity) => entityTicker(entity) ?? entity.name;
+export function pathLabel(path: GraphPath, data: GraphPayload) {
+  const nodes = new Map(data.nodes.map(node => [node.id, node]));
+  return path.nodeIds.map(id => nodes.get(id) ? entityLabel(nodes.get(id)!) : id).join(" → ");
+}
+export function exposureLabel(path: GraphPath, data: GraphPayload) {
+  const exposure = path.exposure;
+  if (!exposure) return "--";
+  const denominator = data.nodes.find(node => node.id === exposure.denominatorEntityId);
+  return `${Number(exposure.pct.toPrecision(4))}% est. of ${denominator ? entityLabel(denominator) : exposure.denominatorEntityId} ${exposure.basis}`;
+}
+export interface GraphNode { entity: SupplyEntity; column: number; hops: number; path: GraphPath | null; related: boolean; }
+/** A selected path has priority over other positions so every highlighted hop remains connected. */
+export function graphNodes(data: GraphPayload, collapsed: readonly string[], selectedPath: GraphPath | null): GraphNode[] {
+  if (!data.entity) return [];
+  const entities = new Map(data.nodes.map(node => [node.id, node]));
+  const result = new Map<string, GraphNode>();
+  result.set(data.entity.id, { entity: data.entity, column: 0, hops: 0, path: null, related: false });
+  const reaches = [...data.upstream, ...data.downstream, ...data.related];
+  const links = new Map(data.links.map(link => [link.id, link]));
+  const addPath = (path: GraphPath, direction: "upstream" | "downstream", selected = false) => {
+    const sign = direction === "upstream" ? -1 : 1;
+    path.nodeIds.forEach((id, index) => {
+      const entity = entities.get(id);
+      if (!entity || path.nodeIds.slice(1, index).some(node => collapsed.includes(node))) return;
+      const previous = result.get(id);
+      const prefixLinks = path.linkIds.slice(0, index);
+      const prefixPath = index === path.hops ? path : { ...path, nodeIds: path.nodeIds.slice(0, index + 1), linkIds: prefixLinks, hops: index, confidence: prefixLinks.reduce((value, id) => value * (links.get(id)?.confidence ?? 0), 1), score: prefixLinks.reduce((value, id) => value * (links.get(id)?.weight ?? 0), 1), exposure: null };
+      const related = prefixLinks.some(id => links.get(id)?.relationship !== "commerce");
+      if (!previous || index < previous.hops || selected) result.set(id, { entity, column: index === 0 ? 0 : sign * index, hops: index, path: index ? prefixPath : null, related });
+    });
+  };
+  for (const reach of reaches) addPath(data.options.ranking === "shortest" ? reach.shortestPath : reach.bestPath, reach.direction);
+  for (const path of data.paths) addPath(path, path.id.startsWith("upstream|") ? "upstream" : "downstream");
+  if (selectedPath) {
+    const reach = reaches.find(row => row.bestPath.id === selectedPath.id || row.shortestPath.id === selectedPath.id);
+    addPath(selectedPath, reach?.direction ?? (selectedPath.id.startsWith("upstream|") ? "upstream" : "downstream"), true);
+  }
+  return [...result.values()].sort((a, b) => a.column - b.column || Number(a.related) - Number(b.related) || (b.path?.score ?? 0) - (a.path?.score ?? 0) || a.entity.name.localeCompare(b.entity.name));
+}