@gloom-sh/terminal 0.0.0-stage → 0.18.5

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

@@ -0,0 +1,222 @@
+import type { DataTableColumn, StatItem } from "../../../components";
+import type { HiringBuildingBoard, HiringBuildingFilter, HiringBuildingHold, HiringBuildingShift, HiringBuildingSkip, HiringCompanyBuilding, HiringMixRow, HiringMovePosting } from "../../../api-client/hiring";
+import { formatNumber } from "../../../utils/format";
+import { countOf, freePreviewNote, previewCantFilter } from "../shared/free-preview";
+import { humanLabel } from "../shared/research-cells";
+import type { AttentionRow } from "./model";
+
+/**
+ * HIRE's Building tab (docs/hiring-app-attention.md): what each company is
+ * building, read from the mix of its new roles. A role family's or a theme's
+ * share of the company's new roles in its recent weeks against its own weeks
+ * before; a shift is one that at least doubled and held every recent week.
+ * Themes are what a role's title says its work is on, as the decision model
+ * confirmed them, never a word match alone.
+ */
+export type BuildingView = "families" | "themes" | "shifts" | "postings";
+export const BUILDING_VIEWS: ReadonlyArray<{ value: BuildingView; label: string }> = [
+  { value: "families", label: "Role families" }, { value: "themes", label: "Themes" }, { value: "shifts", label: "Shifts" }, { value: "postings", label: "Postings" },
+];
+export const isBuildingView = (value: string): value is BuildingView => BUILDING_VIEWS.some((view) => view.value === value);
+export const BUILDING_FILTERS: ReadonlyArray<{ value: HiringBuildingFilter; label: string }> = [{ value: "all", label: "All" }, { value: "function", label: "Role families" }, { value: "theme", label: "Themes" }];
+export const isBuildingFilter = (value: string): value is HiringBuildingFilter => BUILDING_FILTERS.some((filter) => filter.value === value);
+
+const HOLD_LABELS: Record<HiringBuildingHold, string> = {
+  shared_board: "Its board is another covered company's",
+  unmeasured: "Week not measured: the collection changed",
+  recounted: "Postings well above its new roles (re-listed roles)",
+  rescoped: "Its boards changed inside the weeks compared",
+  short_watch: "Too few measured weeks to compare",
+  thin: "Too few roles to compare shares",
+};
+const SKIP_LABELS: Record<HiringBuildingSkip, string> = {
+  unclassified: "Under 80% of roles with a role family",
+  unread_titles: "Some theme titles not read yet",
+};
+const buildingHoldText = (hold: HiringBuildingHold) => HOLD_LABELS[hold] ?? humanLabel(hold);
+const skipText = (skips: readonly HiringBuildingSkip[]) => skips.map((skip) => SKIP_LABELS[skip] ?? humanLabel(skip)).join(", ");
+const kindText = (shift: Pick<HiringBuildingShift, "dimension">) => shift.dimension === "theme" ? "Theme" : "Role family";
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+/** "Oct 12": a week's Monday. */
+function dayLabel(value: string | null | undefined, year = false): string {
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(value ?? "");
+  return match ? `${MONTHS[Number(match[2]) - 1]} ${Number(match[3])}${year ? `, ${match[1]}` : ""}` : "--";
+}
+const count = (value: number | null | undefined) => value == null ? "--" : formatNumber(value, 0);
+/** A share: whole percents from 10%, a tenth under it. */
+const share = (value: number | null | undefined) => value == null ? "--" : value <= 0 ? "0%" : `${formatNumber(value * 100, value < 0.1 ? 1 : 0)}%`;
+/** A change of share in points, as it rounds: "+23 pts", "+5.2 pts", "0 pts". */
+const pointsRounded = (value: number) => Number((value * 100).toFixed(Math.abs(value) < 0.1 ? 1 : 0));
+const points = (value: number) => {
+  const rounded = pointsRounded(value);
+  return rounded === 0 ? "0 pts" : `${rounded > 0 ? "+" : ""}${formatNumber(rounded, Math.abs(value) < 0.1 ? 1 : 0)} pts`;
+};
+/** The sign a change shows, so one that rounds to nothing is not coloured. */
+export const buildingSign = (columnId: string, value: number) => columnId === "change" ? pointsRounded(value) : value;
+const signed = (value: number, decimals = 1) => `${value > 0 ? "+" : ""}${formatNumber(value, decimals)}`;
+const pace = (value: number | null) => value == null ? "from none" : `${formatNumber(value, value >= 10 ? 0 : 1)}x`;
+
+const SHARE_COLUMNS = new Set(["share", "now", "before"]);
+export const BUILDING_SIGNED_COLUMNS = new Set(["change", "z"]);
+/** A building column's number as the pane and the report print it. */
+export function buildingNumber(columnId: string, value: number): string {
+  if (SHARE_COLUMNS.has(columnId)) return share(value);
+  if (columnId === "change") return points(value);
+  if (columnId === "z") return signed(value);
+  return count(value);
+}
+
+const weeksText = (value: number) => countOf(value, "week");
+const ofText = (shift: HiringBuildingShift) => shift.dimension === "function" ? "new roles with a role family" : "new roles";
+
+/** A shift's numbers, as its detail lists them with the sentence that says why. */
+export function shiftFacts(shift: HiringBuildingShift): Array<{ label: string; value: string }> {
+  const weekly = (values: HiringBuildingShift["recent"]["values"]) => values.map((row) => `${dayLabel(row.week)}: ${count(row.roles)} of ${count(row.total)}`).join(", ");
+  return [
+    { label: "Shift", value: kindText(shift) },
+    { label: shift.dimension === "theme" ? "Theme" : "Role family", value: shift.label },
+    { label: "Now", value: `${share(shift.recent.share)} of ${ofText(shift)}, ${count(shift.recent.roles)} of ${count(shift.recent.total)} over the last ${weeksText(shift.recent.weeks)}` },
+    { label: "Before", value: `${share(shift.before.share)}, ${count(shift.before.roles)} of ${count(shift.before.total)} over the ${weeksText(shift.before.weeks)} before` },
+    { label: "Change", value: `${points(shift.change)}, ${pace(shift.ratio)} its share, z ${signed(shift.zScore)}` },
+    ...(shift.recent.values.length ? [{ label: "Recent weeks", value: weekly(shift.recent.values) }] : []),
+    ...(shift.before.values.length ? [{ label: "Weeks before", value: weekly(shift.before.values) }] : []),
+    { label: "Titles", value: count(shift.titles) },
+    ...(shift.topTitles.length ? [{ label: "Top titles", value: shift.topTitles.map((row) => `${row.title.trim()} (${count(row.count)})`).join(", ") }] : []),
+    { label: "Boards", value: shift.sourceTickers.join(", ") },
+    { label: "Week of", value: dayLabel(shift.week, true) },
+    { label: "First computed", value: shift.firstComputedAt },
+  ];
+}
+
+export interface BuildingRow extends AttentionRow {
+  shift?: HiringBuildingShift;
+  mix?: HiringMixRow;
+  jobPosting?: HiringMovePosting;
+}
+export interface BuildingSection {
+  columns: DataTableColumn[];
+  rows: BuildingRow[];
+  empty: string;
+  locked: number;
+}
+export interface BuildingModel {
+  asOf: string | null;
+  week: string | null;
+  preview: boolean;
+  figures: StatItem[];
+  sections: Partial<Record<BuildingView | "board", BuildingSection>>;
+  /** Why a company has no mix, for its report. */
+  held: string | null;
+}
+
+const column = (id: string, label: string, width: number, numeric = false, flex = false): DataTableColumn => ({ id, label, width, align: numeric ? "right" : "left", ...(flex ? { flexGrow: 1 } : {}) });
+// What moved and by how much first, so a narrow pane keeps them; the kind and the evidence after.
+const BOARD_COLUMNS = [column("symbol", "Ticker", 12), column("name", "Company", 20, false, true), column("label", "What", 22),
+  column("now", "Now", 7, true), column("before", "Before", 8, true), column("change", "Change", 10, true), column("roles", "Roles", 7, true), column("kind", "Kind", 12), column("weeks", "Weeks", 8), column("z", "Z-score", 9, true), column("title", "Top title", 26)];
+const SHIFT_COLUMNS = [column("week", "Week of", 12), ...BOARD_COLUMNS.filter((entry) => entry.id !== "symbol" && entry.id !== "name" && entry.id !== "title"), column("title", "Top title", 30, false, true)];
+const mixColumns = (label: string) => [column("label", label, 22, false, true), column("share", "Now", 18, true), column("before", "Before", 8, true), column("change", "Change", 10, true),
+  column("roles", "Roles now", 10, true), column("beforeRoles", "Roles before", 13, true), column("note", "Note", 14)];
+const POSTING_COLUMNS = [column("title", "Role", 32, false, true), column("location", "Location", 24), column("function", "Role family", 16), column("date", "First seen", 12), column("shift", "Shift", 28)];
+
+const topTitle = (shift: HiringBuildingShift) => shift.topTitles[0]?.title.trim() ?? shift.postings[0]?.title.trim() ?? null;
+const shiftRow = (shift: HiringBuildingShift, withWeek = false): BuildingRow => ({
+  id: `${shift.symbol}:${shift.week}:${shift.dimension}:${shift.key}`, symbol: shift.symbol, shift, date: shift.week,
+  values: { ...(withWeek ? { week: shift.week } : {}), symbol: shift.symbol, name: shift.name, kind: kindText(shift), label: shift.label, now: shift.recent.share, before: shift.before.share,
+    change: shift.change, roles: shift.recent.roles, weeks: `${shift.recent.weeks} vs ${shift.before.weeks}`, z: shift.zScore, title: topTitle(shift) },
+});
+
+function boardFigures(board: HiringBuildingBoard): StatItem[] {
+  const { coverage } = board;
+  const held = Object.values(coverage.held).reduce<number>((sum, value) => sum + (value ?? 0), 0);
+  const titles = coverage.themeTitles;
+  return board.week ? [
+    { label: "Role families", value: count(coverage.counts.function ?? 0) },
+    { label: "Themes", value: count(coverage.counts.theme ?? 0) },
+    { label: "Compared", value: count(coverage.measured), detail: `week of ${dayLabel(board.week)}`, detailVariants: [`wk ${dayLabel(board.week)}`, ""] },
+    { label: "Held", value: count(held), detail: "no mix to compare", detailVariants: [""] },
+    ...(titles && titles.titles ? [{ label: "Theme titles read", value: share(titles.read / titles.titles), detail: `${count(titles.read)} of ${count(titles.titles)}`, detailVariants: [""] }] : []),
+  ] : [];
+}
+
+export function buildingBoardModel(board: HiringBuildingBoard, filter: HiringBuildingFilter): BuildingModel {
+  return {
+    asOf: board.coverage.computedAt,
+    week: board.week,
+    preview: board.preview,
+    figures: boardFigures(board),
+    held: null,
+    sections: { board: { columns: BOARD_COLUMNS, rows: board.shifts.map((shift) => shiftRow(shift)), locked: board.preview ? board.locked : 0,
+      empty: !board.week ? "No week has been computed yet." : filter === "all" ? "No company's mix shifted against its own weeks this week." : "None of this kind this week." } },
+  };
+}
+
+const mixRow = (shifted: ReadonlySet<string>) => (row: HiringMixRow): BuildingRow => ({
+  id: `${row.dimension}:${row.key}`, mix: row,
+  values: { label: row.label, share: row.recentShare, before: row.beforeShare, change: row.read ? row.change : null, roles: row.recentRoles, beforeRoles: row.beforeRoles,
+    note: !row.read ? "Reading titles" : shifted.has(`${row.dimension}:${row.key}`) ? "Shift" : null },
+});
+const roleFamily = (value: string | null) => value === "data_ai" ? "Data / AI" : value ? humanLabel(value) : null;
+const postingRow = (shift: HiringBuildingShift) => (posting: HiringMovePosting): BuildingRow => ({
+  id: `${shift.dimension}:${shift.key}:${posting.id}`, url: posting.url, jobPosting: posting, shift,
+  values: { title: posting.title.trim(), location: posting.location ?? posting.country, country: posting.country, shift: `${kindText(shift)}: ${shift.label}`,
+    function: roleFamily(posting.jobFunction), date: posting.firstSeenAt.slice(0, 10) },
+  details: [{ label: "Posting title", value: posting.title.trim() }, { label: "Location", value: posting.location ?? "--" }, { label: "Country", value: posting.country ?? "Unknown" },
+    { label: "Role family", value: roleFamily(posting.jobFunction) ?? "Unclassified" }, { label: "Shift", value: `${kindText(shift)}: ${shift.label}` },
+    { label: "First seen", value: posting.firstSeenAt }, { label: "Board", value: posting.sourceTicker }],
+});
+
+/** A company's mix by role family and by theme, its shifts this week and earlier, and the postings behind this week's. */
+export function companyBuildingModel(data: HiringCompanyBuilding): BuildingModel {
+  const held = data.held ? buildingHoldText(data.held) : null;
+  const window = data.window;
+  const recentWeeks = window?.recent.length ?? 0;
+  const beforeWeeks = window?.before.length ?? 0;
+  const roles = (rows: ReadonlyArray<{ roles: number }>) => rows.reduce((sum, row) => sum + row.roles, 0);
+  const shifted = new Set(data.shifts.map((shift) => `${shift.dimension}:${shift.key}`));
+  const lockedShifts = data.preview ? data.locked.shifts + data.locked.history : 0;
+  const figures: StatItem[] = data.week ? [
+    { label: "Shifts", value: count(data.shifts.length), detail: `week of ${dayLabel(data.week)}`, detailVariants: [`wk ${dayLabel(data.week)}`, ""] },
+    ...(data.preview && lockedShifts ? [{ label: "In Pro", value: count(lockedShifts), detail: "this week and earlier", detailVariants: [""] }] : []),
+    ...(window ? [
+      { label: "Weeks", value: `${recentWeeks} vs ${beforeWeeks}`, detail: "recent vs before", detailVariants: [""] },
+      { label: "Roles", value: `${count(roles(window.recent))} vs ${count(roles(window.before))}`, detail: "recent vs before", detailVariants: [""] },
+    ] : []),
+    ...(held ? [{ label: "No mix", value: held, wide: true }] : data.skipped.length ? [{ label: "In part", value: skipText(data.skipped), wide: true }] : []),
+  ] : [];
+  const empty = held ? `No mix to compare this week: ${held.toLowerCase()}.` : "No mix computed for this company yet.";
+  const shiftsEmpty = held ? empty : lockedShifts ? "This company's shifts are in Pro." : "No role family or theme shifted against this company's own weeks.";
+  return {
+    asOf: data.shifts[0]?.computedAt ?? data.history[0]?.computedAt ?? null,
+    week: data.week,
+    preview: data.preview,
+    figures,
+    held,
+    sections: {
+      families: { columns: mixColumns("Role family"), rows: data.functions.map(mixRow(shifted)), locked: data.preview ? data.locked.functions : 0,
+        empty: held ? empty : data.skipped.includes("unclassified") ? "Too few roles carry a role family to compare." : empty },
+      themes: { columns: mixColumns("Theme"), rows: data.themes.map(mixRow(shifted)), locked: data.preview ? data.locked.themes : 0,
+        empty: held ? empty : "No role names a theme in the weeks compared." },
+      shifts: { columns: SHIFT_COLUMNS, rows: [...data.shifts.map((shift) => shiftRow(shift, true)), ...data.history.map((shift) => shiftRow(shift, true))], locked: lockedShifts, empty: shiftsEmpty },
+      // Behind one shift, every row would name it.
+      postings: { columns: data.shifts.length > 1 ? POSTING_COLUMNS : POSTING_COLUMNS.filter((entry) => entry.id !== "shift"), rows: data.shifts.flatMap((shift) => shift.postings.map(postingRow(shift))), locked: 0,
+        empty: data.shifts.length ? "No posting is listed behind this week's shifts." : shiftsEmpty },
+    },
+  };
+}
+
+/**
+ * The lock line of a free Building read: what free shows and what Pro adds.
+ * Null when nothing is held back. A free board is the same three whatever
+ * `filter` asked for.
+ */
+export function buildingPreviewNote(data: HiringBuildingBoard | HiringCompanyBuilding, filter?: HiringBuildingFilter): string | null {
+  if (!data.preview) return null;
+  if ("filter" in data) {
+    const shows = `${data.shifts.length} of ${count(data.total)} shifts${filter && filter !== "all" ? `: ${previewCantFilter(["dimension"])}` : ""}`;
+    return data.locked > 0 ? freePreviewNote({ shows, adds: `the other ${count(data.locked)} and every posting behind them` }) : null;
+  }
+  const { functions, themes, shifts, history } = data.locked;
+  const adds = [functions + themes > 0 ? countOf(functions + themes, "more family or theme", "more families and themes") : "", shifts > 0 ? countOf(shifts, "shift") : "", history > 0 ? countOf(history, "earlier shift") : ""].filter(Boolean);
+  return adds.length ? freePreviewNote({ shows: "the three largest families and themes, and the shifts the free board shows", adds: adds.join(", ") }) : null;
+}

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

@@ -0,0 +1,172 @@
+import { useCallback, useMemo, useRef, type ReactNode } from "react";
+import { isAccessDenied } from "../../../api-client/errors";
+import type { HiringBuildingFilter, HiringBuildingShift } from "../../../api-client/hiring";
+import { ChartTableHeader, DataTableView, PageStackView, PaneFooterScope, PaneLinkMenu, QueryBar, usePagedRows, usePaneStatusFooter, useTableLoadMore, withCountryFlag, type PaneHint } from "../../../components";
+import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { DetailReader, type DetailFact } from "../../../components/reader/detail-reader";
+import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import { useThemeColors } from "../../../theme/theme-context";
+import { Text, useRendererHost, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
+import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { Blurred, LockedOverlay, UpgradeLabel } from "../shared/locked-rows";
+import { useOpenDescription } from "../shared/open-description";
+import { listingCell, missingCell, shareCell, signedColor, toneColor, withoutQuietColumns } from "../shared/research-cells";
+import { BUILDING_FILTERS, BUILDING_SIGNED_COLUMNS, BUILDING_VIEWS, buildingBoardModel, buildingNumber, buildingSign, companyBuildingModel, isBuildingFilter, isBuildingView, shiftFacts, type BuildingRow } from "./building-model";
+import { cachedBuilding, fetchBuilding, loadBuilding, validateBuilding, type BuildingPayload } from "./client";
+import { sortAttentionRows } from "./model";
+
+const rowId = (row: BuildingRow) => row.id;
+const locked = (row: BuildingRow) => row.id.startsWith("locked:");
+/** A company with no shift leaves the Note column out. */
+const QUIET_COLUMNS: Record<string, readonly string[]> = { note: [""], title: [""] };
+/** Postings a shift's detail links to, so the sentence after them stays in view; the Postings view lists them all. */
+const DETAIL_POSTINGS = 3;
+
+export interface HiringBuildingViewProps {
+  symbol?: string;
+  width: number;
+  height: number;
+  focused: boolean;
+  /** Plan and session, so a cached read is never shown to the wrong account. */
+  accessKey: string;
+  /** The board opens a company on the same tab, as Moves does. */
+  company?: { open: string | null; onOpen: (symbol: string | null) => void; render: (symbol: string, width: number, height: number) => ReactNode };
+}
+
+/**
+ * HIRE's Building tab. Alone, the latest week's shifts: role families and
+ * themes whose share of a company's new roles rose against its own weeks.
+ * Enter opens the company, `e` says why. On a ticker, the company's whole
+ * mix by role family and by theme, now and before, its shifts this week and
+ * earlier, and the postings behind this week's.
+ */
+export function HiringBuildingView({ symbol, width, height, focused, accessKey, company }: HiringBuildingViewProps) {
+  const colors = useThemeColors();
+  const desktop = !!useUiCapabilities().nativePaneChrome;
+  const host = useRendererHost();
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const openDescription = useOpenDescription();
+  const upgrade = useCloudUpgradeAction("hire");
+  const scope = `hiring:building:${symbol ?? "board"}`;
+  const [openingFilter] = usePaneSettingValue<string>("buildingDimension", "all");
+  const [storedFilter, setFilter] = usePluginPaneState<string>("hiring:building:filter", openingFilter);
+  const filter: HiringBuildingFilter = isBuildingFilter(storedFilter) ? storedFilter : "all";
+  const [openingView] = usePaneSettingValue<string>("buildingView", "families");
+  const [storedView, setView] = usePluginPaneState<string>(`${scope}:view`, openingView);
+  const view = isBuildingView(storedView) ? storedView : "families";
+  const [snapshotSetting] = usePaneSettingValue<BuildingPayload | null>("buildingSnapshot", null);
+  // A `gloom shot` hands the payload in; a company opened from a board snapshot still loads its own.
+  const snapshot = useMemo(() => {
+    try {
+      const payload = snapshotSetting ? validateBuilding(snapshotSetting) : null;
+      return payload && ("filter" in payload ? !symbol : payload.symbol.toUpperCase() === symbol?.toUpperCase()) ? payload : null;
+    } catch { return null; }
+  }, [snapshotSetting, symbol]);
+  const loader = useCallback((force: boolean) => snapshot ? Promise.resolve({ payload: snapshot, stale: false, refreshError: null }) : loadBuilding(symbol, accessKey, filter, force), [snapshot, symbol, accessKey, filter]);
+  const resource = useAsyncResource(loader, { initialData: () => cachedBuilding(symbol, accessKey, filter), clearOnError: isAccessDenied, keepPreviousData: true });
+  const data = resource.data?.payload;
+  const model = useMemo(() => !data ? null : "filter" in data ? buildingBoardModel(data, filter) : companyBuildingModel(data), [data, filter]);
+  const sectionId = symbol ? view : "board";
+  const section = model?.sections[sectionId];
+  const pageLoader = useCallback(async ({ offset, signal }: { offset: number; signal: AbortSignal; force: boolean }) => {
+    const payload = offset === 0 && data ? data : await fetchBuilding(undefined, { filter, offset, limit: 100 }, undefined, signal);
+    if (!("filter" in payload)) return { rows: [], hasMore: false, nextOffset: null };
+    const next = !payload.preview && offset + payload.shifts.length < payload.total ? offset + payload.shifts.length : null;
+    return { rows: buildingBoardModel(payload, filter).sections.board!.rows, hasMore: !snapshot && next !== null, nextOffset: next };
+  }, [data, filter, snapshot]);
+  const paged = usePagedRows(data && !symbol ? pageLoader : null, { getId: rowId });
+  const sectionRows = !symbol && paged.status !== "idle" ? paged.rows : section?.rows ?? [];
+  // The server's order (the clearest shifts first, the mix by its share now) until a header is clicked.
+  const [sort, setSort] = usePluginPaneState<{ column: string; direction: "asc" | "desc" } | null>(`${scope}:${sectionId}:sort`, null);
+  const lockedRows = Math.min(3, section?.locked ?? 0);
+  const upgradeText = symbol ? "Upgrade for the whole mix" : "Upgrade for all shifts";
+  const rows = useMemo(() => [...(sort ? sortAttentionRows(sectionRows, sort.column, sort.direction) : sectionRows) as BuildingRow[],
+    ...Array.from({ length: lockedRows }, (_, index): BuildingRow => ({ id: `locked:${index}`, values: {} }))], [sectionRows, sort, lockedRows]);
+  const dataRows = useMemo(() => rows.filter((row) => !locked(row)), [rows]);
+  const columns = useMemo(() => !section ? [] : withoutQuietColumns(section.columns, dataRows, (row, id) => row.values[id] ?? "", QUIET_COLUMNS), [section, dataRows]);
+  const maxShare = Math.max(0, ...dataRows.map((row) => typeof row.values.share === "number" ? row.values.share : 0));
+  const [selectedId, setSelected] = usePluginPaneState<string | null>(`${scope}:${sectionId}:selected`, null);
+  const openCompany = company?.open ?? null;
+  const [openRowId, setOpenRow] = usePluginPaneState<string | null>(`${scope}:open`, null);
+  const selected = rows.find((row) => row.id === selectedId) ?? rows[0] ?? null;
+  const opened = dataRows.find((row) => row.id === openRowId) ?? null;
+  const detailOpen = !!openCompany || !!opened;
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+  const scrollMore = useTableLoadMore(scrollRef, paged.hasMore && !detailOpen, paged.loadMore);
+  useAutoRefresh(resource.updatedAt, resource.load);
+  usePaneRefreshKey(() => { void resource.reload(); paged.reload(); }, { focused: focused && !detailOpen });
+
+  const subject = selected?.symbol ?? symbol;
+  // A shift opens its first posting; a posting row its own.
+  const sourceRow = opened ?? selected;
+  const source = sourceRow?.jobPosting?.url ?? sourceRow?.shift?.postings[0]?.url ?? null;
+  const hints: PaneHint[] = [
+    ...(source ? [{ id: "source", key: "o", label: "pen source", onPress: () => void host.openExternal(source) }] : []),
+    // On a company Enter already opens a shift or a posting.
+    ...(!symbol && selected?.shift && !opened ? [{ id: "evidence", key: "e", label: "vidence", title: "Why it shifted", onPress: () => setOpenRow(selected.id) }] : []),
+    ...(subject && !opened ? [
+      { id: "description", key: "d", label: "es", onPress: () => openDescription(subject) },
+      { id: "financials", key: "f", label: "a", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol: subject }) },
+      { id: "chart", key: "g", label: "raph", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: subject }) },
+      { id: "related", key: "a", label: "pps", title: "App attention", onPress: () => createPaneFromTemplate("apps-pane", { symbol: subject }) },
+    ] : []),
+    ...(model?.preview ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: upgrade }] : []),
+  ];
+  usePaneStatusFooter({ registrationId: `${scope}:status`, enabled: !openCompany, loading: resource.loading || paged.loadingMore, error: data ? resource.error ?? paged.moreError?.message ?? paged.error?.message : null, stale: resource.data?.stale,
+    info: [...(model?.asOf ? [{ id: "observed", asOf: true, parts: [{ text: `as of ${model.asOf.slice(0, 10)}`, tone: "muted" as const }] }] : []), ...(model?.preview ? [{ id: "preview", parts: [{ text: "Pro preview", tone: "warning" as const }] }] : [])], hints });
+
+  const query = <QueryBar width={width} filters={symbol
+    ? [{ id: "view", label: "View", value: view, options: BUILDING_VIEWS.map((entry) => ({ ...entry })), onChange: (value: string) => { setView(value); setOpenRow(null); } }]
+    : [{ id: "dimension", label: "Show", value: filter, defaultValue: "all", options: BUILDING_FILTERS.map((entry) => ({ ...entry })), onChange: (value: string) => { setFilter(value); setOpenRow(null); } }]} />;
+  const shiftDetail = (shift: HiringBuildingShift): DetailFact[] => [
+    ...shiftFacts(shift),
+    // The postings behind it, each opening the employer's page.
+    ...shift.postings.slice(0, DETAIL_POSTINGS).map((posting, index): DetailFact => ({ label: index === 0 ? "Postings" : "", value: `${posting.title.trim()}${posting.location ? `, ${posting.location}` : ""}`,
+      ...(posting.url ? { link: { label: "Open posting", onOpen: () => void host.openExternal(posting.url!) } } : {}) })),
+    ...(shift.postings.length > DETAIL_POSTINGS ? [{ label: "", value: `${shift.postings.length - DETAIL_POSTINGS} more in ${symbol ? "the" : "the company's"} Postings view` }] : []),
+  ];
+  const detailTitle = openCompany ?? (opened?.jobPosting ? opened.jobPosting.title.trim() : opened?.shift ? `${opened.shift.symbol} · ${opened.shift.label}` : undefined);
+  const detail = openCompany && company ? <PaneFooterScope active>{company.render(openCompany, width, height - 1)}</PaneFooterScope>
+    : opened ? <PaneLinkMenu><DetailReader resetScrollKey={opened.id} width={width}
+      facts={opened.jobPosting ? opened.details ?? [] : opened.shift ? shiftDetail(opened.shift) : []} body={opened.jobPosting ? null : opened.shift?.why ?? null} note={opened.jobPosting?.url ?? null} /></PaneLinkMenu> : null;
+  // A mix row opens its shift, when it has one this week.
+  const shiftOf = (row: BuildingRow) => row.mix ? model?.sections.shifts?.rows.find((entry) => entry.shift && entry.shift.week === model.week && `${entry.shift.dimension}:${entry.shift.key}` === row.id) ?? null : null;
+  return <PageStackView focused={focused} detailOpen={detailOpen} onBack={() => { company?.onOpen(null); setOpenRow(null); }} detailTitle={detailTitle} detailContent={detail}
+    rootContent={<DataTableView columns={columns} items={model && section ? rows : []} rootWidth={width} rootHeight={height} focused={focused && !detailOpen} scrollRef={scrollRef} onBodyScrollActivity={scrollMore}
+      status={!data ? { loading: resource.loading, error: resource.error, subject: "what companies are building" } : undefined}
+      rootBefore={<ChartTableHeader width={width} height={height} tableRows={rows.length} tableColumns={columns} query={query} figures={model?.figures} />}
+      selection={{ kind: "id", selectedId: selected?.id ?? null, getId: rowId, onChange: setSelected }} getItemKey={rowId}
+      sortColumnId={sort?.column ?? null} sortDirection={sort?.direction ?? "desc"} onHeaderClick={(column) => setSort((old) => ({ column, direction: old?.column === column && old.direction === "desc" ? "asc" : "desc" }))}
+      onActivate={(row) => {
+        if (locked(row)) return void upgrade();
+        if (!symbol && row.symbol && company) return company.onOpen(row.symbol);
+        const target = row.shift || row.jobPosting ? row : shiftOf(row);
+        if (!target) return;
+        // A mix row's shift opens from the Shifts view, where its detail lives.
+        if (row.mix) setView("shifts");
+        setOpenRow(target.id);
+      }}
+      renderCell={(row, column, _index, state) => {
+        if (locked(row)) {
+          if (!desktop && column.id === columns[0]?.id && row.id === "locked:0") return { text: upgradeText, content: <UpgradeLabel text={upgradeText} onPress={upgrade} role="attention-upgrade" /> };
+          return desktop ? { text: "", content: <Blurred><Text fg={colors.textDim}>Hidden</Text></Blurred> } : { text: "░░░░", color: colors.textDim };
+        }
+        const value = row.values[column.id];
+        // A family or theme with no shift has nothing to note.
+        if (column.id === "note" && value == null) return { text: "" };
+        if (value == null || value === "") return missingCell(colors);
+        if (column.id === "symbol" && typeof value === "string") return listingCell(value, colors, state.selected);
+        // Every shift is news, as a first or a spike is on the other tabs.
+        if (column.id === "kind" && typeof value === "string") return { text: value, color: toneColor("positive", colors), keepColorWhenSelected: true };
+        if (column.id === "note" && typeof value === "string") return { text: value, value, color: toneColor(value === "Shift" ? "positive" : "muted", colors), keepColorWhenSelected: value === "Shift" };
+        if (typeof value === "number") {
+          const text = buildingNumber(column.id, value);
+          if (column.id === "share") return { ...shareCell(text, maxShare ? value / maxShare : null, column.width, colors, state.selected), value };
+          return { text, value, color: BUILDING_SIGNED_COLUMNS.has(column.id) ? signedColor(buildingSign(column.id, value), colors) : column.id === "before" || column.id === "beforeRoles" ? colors.textDim : colors.text };
+        }
+        if (column.id === "location" && row.values.country) return withCountryFlag({ text: value, value, color: colors.text }, String(row.values.country), desktop);
+        return { text: value, value, color: column.id === "name" || column.id === "title" || column.id === "label" ? colors.textBright : column.id === "date" || column.id === "week" || column.id === "weeks" ? colors.textDim : colors.text };
+      }} selectedTextOverridesCellColor showHorizontalScrollbar resetScrollKey={`${scope}:${sectionId}:${filter}`}
+      emptyStateTitle={section?.empty ?? ""} bodyAfter={lockedRows && desktop ? <LockedOverlay rows={lockedRows} text={upgradeText} onPress={upgrade} role="attention-upgrade" /> : undefined} />}
+  />;
+}

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

@@ -0,0 +1,185 @@
+import { apiClient } from "../../../api-client";
+import type { AppAttentionFilter, AppAttentionPayload, AppRankPayload } from "../../../api-client/app-attention";
+import type { HiringBoard, HiringBuildingBoard, HiringBuildingFilter, HiringBuildingShift, HiringCompanyBuilding, HiringCompanyMoves, HiringCompanySignals, HiringMixRow, HiringMove, HiringMovePosting, HiringMovesBoard, HiringMovesFilter, HiringMoveWeek, HiringPayload, HiringSignalGroup, HiringSignalsBoard, HiringSignalsFilter, HiringSummary, HiringWeekSignal } from "../../../api-client/hiring";
+import type { CloudJobsPostingDetail } from "../../../api-client/types";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+import type { AppFocus, AttentionKind } from "./model";
+
+export type AttentionPayload = HiringBoard | HiringPayload | AppAttentionPayload;
+export const attentionCache = createPluginCache<AttentionPayload>({ kind: "company-attention", source: "gloom-cloud", schemaVersion: 1, policy: { staleMs: 30 * 60_000, expireMs: 7 * 86_400_000 } });
+export type MovesPayload = HiringMovesBoard | HiringCompanyMoves;
+export const movesCache = createPluginCache<MovesPayload>({ kind: "hiring-moves", source: "gloom-cloud", schemaVersion: 1, policy: { staleMs: 30 * 60_000, expireMs: 7 * 86_400_000 } });
+export type SignalsPayload = HiringSignalsBoard | HiringCompanySignals;
+export const signalsCache = createPluginCache<SignalsPayload>({ kind: "hiring-signals", source: "gloom-cloud", schemaVersion: 1, policy: { staleMs: 30 * 60_000, expireMs: 7 * 86_400_000 } });
+export type BuildingPayload = HiringBuildingBoard | HiringCompanyBuilding;
+export const buildingCache = createPluginCache<BuildingPayload>({ kind: "hiring-building", source: "gloom-cloud", schemaVersion: 1, policy: { staleMs: 30 * 60_000, expireMs: 7 * 86_400_000 } });
+export const appRankCache = createPluginCache<AppRankPayload>({ kind: "app-rank-history", source: "gloom-cloud", schemaVersion: 1, policy: { staleMs: 30 * 60_000, expireMs: 7 * 86_400_000 } });
+const finite = (value: unknown) => typeof value === "number" && Number.isFinite(value);
+const positive = (value: unknown) => finite(value) && (value as number) >= 0;
+const fraction = (value: unknown) => positive(value) && (value as number) <= 1;
+const date = (value: unknown) => typeof value === "string" && Number.isFinite(Date.parse(value));
+const url = (value: unknown) => { try { return typeof value === "string" && ["https:", "http:"].includes(new URL(value).protocol); } catch { return false; } };
+function numericTree(value: unknown): boolean {
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every(numericTree);
+  if (value && typeof value === "object") return Object.values(value).every(numericTree);
+  return true;
+}
+function hiringCompany(row: HiringSummary): boolean {
+  return !!row && typeof row.symbol === "string" && typeof row.name === "string" && fraction(row.mappingConfidence)
+    && ["ok", "collecting", "stale", "uncovered"].includes(row.status) && positive(row.historyWeeks)
+    && (row.latest === null || (!!row.latest && date(row.latest.week) && date(row.latest.observedAt) && positive(row.latest.openCount)
+      && (row.latest.remoteShare === null || fraction(row.latest.remoteShare)) && fraction(row.latest.confidence)));
+}
+export function validateAttention(kind: AttentionKind, payload: AttentionPayload): AttentionPayload {
+  let valid = !!payload && date(payload.generatedAt) && numericTree(payload);
+  if (valid && kind === "hiring") {
+    const data = payload as HiringBoard | HiringPayload;
+    valid = typeof data.preview === "boolean" && ("companies" in data
+      ? Array.isArray(data.companies) && data.companies.every(hiringCompany) && positive(data.locked)
+      : hiringCompany(data) && Array.isArray(data.series) && data.series.every((row) => date(row.week) && positive(row.openCount))
+        && [data.functions, data.seniority, data.countries, data.locations].every((rows) => Array.isArray(rows) && rows.every((row) => typeof row.label === "string" && positive(row.count) && fraction(row.share)))
+        && Array.isArray(data.peers) && data.peers.every(hiringCompany) && Array.isArray(data.signals)
+        && Array.isArray(data.evidence) && data.evidence.every((row) => typeof row.title === "string" && date(row.observedAt) && fraction(row.confidence) && (row.url === null || url(row.url)))
+        && !!data.coverage && typeof data.coverage.comparability === "string" && !!data.locked);
+  } else if (valid) {
+    const data = payload as AppAttentionPayload;
+    valid = ["pro", "preview"].includes(data.access) && ["ready", "collecting", "unavailable"].includes(data.status)
+      && !!data.summary && positive(data.summary.appCount) && !!data.coverage && Array.isArray(data.coverage.limitations)
+      && Array.isArray(data.apps) && data.apps.every((row) => typeof row.appId === "string" && typeof row.name === "string" && typeof row.country === "string" && date(row.observedAt) && url(row.appUrl) && fraction(row.confidence) && (row.rank === null || positive(row.rank)) && (row.rating === null || (positive(row.rating) && row.rating <= 5)))
+      && Array.isArray(data.history) && data.history.every((row) => date(row.date))
+      && [data.companies, data.peers, data.countries, data.spreads, data.evidence].every(Array.isArray)
+      && data.evidence.every((row) => url(row.sourceUrl) && date(row.observedAt) && fraction(row.confidence)) && !!data.locked;
+  }
+  if (!valid) throw new Error(`The server returned unreadable ${kind === "hiring" ? "hiring observations" : "app attention"}.`);
+  return payload;
+}
+export async function fetchAttention(kind: AttentionKind, symbol?: string, filters: AppAttentionFilter = {}, client: Pick<typeof apiClient, "getCloudHiring" | "getCloudAppAttention"> = apiClient, signal?: AbortSignal) {
+  try {
+    const data = validateAttention(kind, kind === "hiring" ? await client.getCloudHiring(symbol, filters, signal) : await client.getCloudAppAttention({ ...filters, symbol }, signal));
+    if (symbol && (!("symbol" in data) || data.symbol?.toUpperCase() !== symbol.toUpperCase() && data.requestedSymbol?.toUpperCase() !== symbol.toUpperCase())) throw new Error("The server returned observations for a different company.");
+    return data;
+  } catch (error) { throw unavailableOnServer(error, `${kind === "hiring" ? "Hiring observations" : "App attention"} are not available yet.`, [404, 503]); }
+}
+// Both identity and entitlement partition the persistent cache.
+const cacheKey = (kind: AttentionKind, symbol: string | undefined, access: string, filters: AppAttentionFilter) => `${kind}:${symbol ?? "board"}:${access}:${JSON.stringify(filters)}`;
+export const cachedAttention = (kind: AttentionKind, symbol: string | undefined, access: string, filters: AppAttentionFilter) => cachedCloudResource(attentionCache, cacheKey(kind, symbol, access, filters), (data) => validateAttention(kind, data));
+export const loadAttention = (kind: AttentionKind, symbol: string | undefined, access: string, filters: AppAttentionFilter, force = false) => loadCloudResource(attentionCache, cacheKey(kind, symbol, access, filters), () => fetchAttention(kind, symbol, filters), { force, validate: (data) => validateAttention(kind, data) });
+
+const SIGNALS = new Set(["accelerating", "slowing", "with_peers", null]);
+const hiringMove = (row: HiringMove) => !!row && typeof row.symbol === "string" && typeof row.name === "string" && date(row.week) && positive(row.newRoles)
+  && !!row.baseline && positive(row.baseline.mean) && Array.isArray(row.baseline.values) && finite(row.zScore) && !!row.peers && typeof row.peers.label === "string"
+  && SIGNALS.has(row.signal) && Array.isArray(row.drivers) && row.drivers.every((driver) => typeof driver.label === "string" && positive(driver.newRoles))
+  && Array.isArray(row.topTitles) && typeof row.why === "string" && Array.isArray(row.sourceTickers);
+const moveWeek = (row: HiringMoveWeek) => !!row && date(row.week) && typeof row.measured === "boolean" && Array.isArray(row.excluded);
+const movePosting = (row: HiringMovePosting) => !!row && typeof row.title === "string" && date(row.firstSeenAt) && (row.url === null || url(row.url));
+export function validateMoves(payload: MovesPayload): MovesPayload {
+  const valid = !!payload && date(payload.generatedAt) && typeof payload.preview === "boolean" && numericTree(payload) && ("moves" in payload
+    ? (payload.week === null || date(payload.week)) && Array.isArray(payload.moves) && payload.moves.every(hiringMove) && positive(payload.total) && positive(payload.locked) && !!payload.coverage?.signals
+    : typeof payload.symbol === "string" && (payload.latest === null || hiringMove(payload.latest)) && (payload.week === null || moveWeek(payload.week))
+      && Array.isArray(payload.weeks) && payload.weeks.every(moveWeek) && Array.isArray(payload.history) && !!payload.evidence
+      && [payload.evidence.added, payload.evidence.closed].every((rows) => Array.isArray(rows) && rows.every(movePosting)) && !!payload.locked);
+  if (!valid) throw new Error("The server returned unreadable hiring moves.");
+  return payload;
+}
+export interface MovesQuery { filter?: HiringMovesFilter; offset?: number; limit?: number }
+export async function fetchMoves(symbol: string | undefined, query: MovesQuery = {}, client: Pick<typeof apiClient, "getCloudHiringMoves"> = apiClient, signal?: AbortSignal) {
+  try {
+    const data = validateMoves(await client.getCloudHiringMoves(symbol, { limit: query.limit, offset: query.offset, signal: query.filter }, signal));
+    if (symbol && (!("symbol" in data) || data.symbol.toUpperCase() !== symbol.toUpperCase() && data.requestedSymbol?.toUpperCase() !== symbol.toUpperCase())) throw new Error("The server returned moves for a different company.");
+    return data;
+  } catch (error) { throw unavailableOnServer(error, "Hiring moves are not available yet.", [404, 503]); }
+}
+const movesKey = (symbol: string | undefined, access: string, filter: HiringMovesFilter) => `${symbol ?? `board:${filter}`}:${access}`;
+export const cachedMoves = (symbol: string | undefined, access: string, filter: HiringMovesFilter) => cachedCloudResource(movesCache, movesKey(symbol, access, filter), validateMoves);
+export const loadMoves = (symbol: string | undefined, access: string, filter: HiringMovesFilter, force = false) => loadCloudResource(movesCache, movesKey(symbol, access, filter), () => fetchMoves(symbol, { filter }), { force, validate: validateMoves });
+
+const KINDS = new Set(["new_country", "new_city", "location_spike", "function_spike", "new_role_type"]);
+const weekSignal = (row: HiringWeekSignal) => !!row && typeof row.symbol === "string" && typeof row.name === "string" && date(row.week) && KINDS.has(row.kind)
+  && ["expansion", "anomalies"].includes(row.group) && typeof row.key === "string" && typeof row.label === "string" && positive(row.newRoles)
+  && !!row.history && date(row.history.watchedSince) && positive(row.history.priorPostings) && (row.history.priorShare === null || fraction(row.history.priorShare))
+  && (row.baseline === null || (!!row.baseline && positive(row.baseline.mean) && Array.isArray(row.baseline.values))) && Array.isArray(row.flags)
+  && Array.isArray(row.topTitles) && Array.isArray(row.places) && Array.isArray(row.postings) && row.postings.every(movePosting)
+  && typeof row.why === "string" && Array.isArray(row.sourceTickers);
+export function validateSignals(payload: SignalsPayload): SignalsPayload {
+  const valid = !!payload && date(payload.generatedAt) && typeof payload.preview === "boolean" && numericTree(payload) && ("group" in payload
+    ? ["expansion", "anomalies"].includes(payload.group) && (payload.week === null || date(payload.week)) && Array.isArray(payload.signals) && payload.signals.every(weekSignal)
+      && positive(payload.total) && positive(payload.locked) && !!payload.coverage?.counts
+    : typeof payload.symbol === "string" && (payload.week === null || date(payload.week)) && (payload.watchedSince === null || date(payload.watchedSince))
+      && Array.isArray(payload.signals) && payload.signals.every(weekSignal) && Array.isArray(payload.history) && payload.history.every(weekSignal)
+      && Array.isArray(payload.skipped) && !!payload.locked);
+  if (!valid) throw new Error("The server returned unreadable hiring signals.");
+  return payload;
+}
+export interface SignalsQuery { filter?: HiringSignalsFilter; offset?: number; limit?: number }
+/** A group's board, or a company's signals (both groups; the view keeps its own). */
+export async function fetchSignals(group: HiringSignalGroup, symbol: string | undefined, query: SignalsQuery = {}, client: Pick<typeof apiClient, "getCloudHiringSignals" | "getCloudHiringCompanySignals"> = apiClient, signal?: AbortSignal) {
+  try {
+    const data = validateSignals(symbol ? await client.getCloudHiringCompanySignals(symbol, signal) : await client.getCloudHiringSignals(group, { limit: query.limit, offset: query.offset, kind: query.filter }, signal));
+    if (symbol && (!("symbol" in data) || data.symbol.toUpperCase() !== symbol.toUpperCase() && data.requestedSymbol?.toUpperCase() !== symbol.toUpperCase())) throw new Error("The server returned signals for a different company.");
+    if (!symbol && (!("group" in data) || data.group !== group)) throw new Error("The server returned another tab's signals.");
+    return data;
+  } catch (error) { throw unavailableOnServer(error, "Hiring signals are not available yet.", [404, 503]); }
+}
+const signalsKey = (group: HiringSignalGroup, symbol: string | undefined, access: string, filter: HiringSignalsFilter) => `${symbol ?? `${group}:${filter}`}:${access}`;
+export const cachedSignals = (group: HiringSignalGroup, symbol: string | undefined, access: string, filter: HiringSignalsFilter) => cachedCloudResource(signalsCache, signalsKey(group, symbol, access, filter), validateSignals);
+export const loadSignals = (group: HiringSignalGroup, symbol: string | undefined, access: string, filter: HiringSignalsFilter, force = false) => loadCloudResource(signalsCache, signalsKey(group, symbol, access, filter), () => fetchSignals(group, symbol, { filter }), { force, validate: validateSignals });
+
+const DIMENSIONS = new Set(["function", "theme"]);
+const mixRow = (row: HiringMixRow) => !!row && DIMENSIONS.has(row.dimension) && typeof row.key === "string" && typeof row.label === "string"
+  && positive(row.recentRoles) && fraction(row.recentShare) && positive(row.beforeRoles) && fraction(row.beforeShare) && finite(row.change) && typeof row.read === "boolean";
+const shiftPart = (part: HiringBuildingShift["recent"]) => !!part && positive(part.weeks) && positive(part.roles) && positive(part.total) && fraction(part.share) && Array.isArray(part.values);
+const buildingShift = (row: HiringBuildingShift) => !!row && typeof row.symbol === "string" && typeof row.name === "string" && date(row.week) && DIMENSIONS.has(row.dimension)
+  && typeof row.key === "string" && typeof row.label === "string" && shiftPart(row.recent) && shiftPart(row.before) && finite(row.change) && finite(row.zScore)
+  && Array.isArray(row.topTitles) && Array.isArray(row.postings) && row.postings.every(movePosting) && typeof row.why === "string" && Array.isArray(row.sourceTickers);
+export function validateBuilding(payload: BuildingPayload): BuildingPayload {
+  const valid = !!payload && date(payload.generatedAt) && typeof payload.preview === "boolean" && numericTree(payload) && ("shifts" in payload && "filter" in payload
+    ? (payload.week === null || date(payload.week)) && Array.isArray(payload.shifts) && payload.shifts.every(buildingShift) && positive(payload.total) && positive(payload.locked) && !!payload.coverage?.counts
+    : "functions" in payload && typeof payload.symbol === "string" && (payload.week === null || date(payload.week)) && Array.isArray(payload.functions) && payload.functions.every(mixRow)
+      && Array.isArray(payload.themes) && payload.themes.every(mixRow) && Array.isArray(payload.shifts) && payload.shifts.every(buildingShift)
+      && Array.isArray(payload.history) && payload.history.every(buildingShift) && Array.isArray(payload.skipped) && !!payload.locked);
+  if (!valid) throw new Error("The server returned an unreadable hiring mix.");
+  return payload;
+}
+export interface BuildingQuery { filter?: HiringBuildingFilter; offset?: number; limit?: number }
+/** The Building board, or one company's mix and shifts. */
+export async function fetchBuilding(symbol: string | undefined, query: BuildingQuery = {}, client: Pick<typeof apiClient, "getCloudHiringBuilding" | "getCloudHiringCompanyBuilding"> = apiClient, signal?: AbortSignal) {
+  try {
+    const data = validateBuilding(symbol ? await client.getCloudHiringCompanyBuilding(symbol, signal) : await client.getCloudHiringBuilding({ limit: query.limit, offset: query.offset, dimension: query.filter }, signal));
+    if (symbol && (!("symbol" in data) || data.symbol.toUpperCase() !== symbol.toUpperCase() && data.requestedSymbol?.toUpperCase() !== symbol.toUpperCase())) throw new Error("The server returned a hiring mix for a different company.");
+    if (!symbol && !("filter" in data)) throw new Error("The server returned a company's mix for the board.");
+    return data;
+  } catch (error) { throw unavailableOnServer(error, "What companies are building is not available yet.", [404, 503]); }
+}
+const buildingKey = (symbol: string | undefined, access: string, filter: HiringBuildingFilter) => `${symbol ?? `board:${filter}`}:${access}`;
+export const cachedBuilding = (symbol: string | undefined, access: string, filter: HiringBuildingFilter) => cachedCloudResource(buildingCache, buildingKey(symbol, access, filter), validateBuilding);
+export const loadBuilding = (symbol: string | undefined, access: string, filter: HiringBuildingFilter, force = false) => loadCloudResource(buildingCache, buildingKey(symbol, access, filter), () => fetchBuilding(symbol, { filter }), { force, validate: validateBuilding });
+
+export async function fetchAppRank(focus: AppFocus, days: number, offset = 0, signal?: AbortSignal, client: Pick<typeof apiClient, "getCloudAppRankHistory"> = apiClient, limit = 500) {
+  const data = await client.getCloudAppRankHistory(focus.store, focus.appId, { country: focus.country, chart: focus.chart, days, offset, limit }, signal);
+  if (!data || data.appId !== focus.appId || data.store !== focus.store || !["pro", "preview"].includes(data.access)
+    || !Array.isArray(data.rankHistory) || !data.rankHistory.every((row) => row.appId === focus.appId && row.store === focus.store && row.country === focus.country && row.chart === focus.chart && date(row.date) && date(row.observedAt) && url(row.sourceUrl) && (row.rank === null || positive(row.rank))) || !data.page || !numericTree(data)) throw new Error("The server returned unreadable app rank history.");
+  return data;
+}
+export const loadAppRank = (focus: AppFocus, access: string, days: number, force = false) => loadCloudResource(appRankCache, `${access}:${focus.store}:${focus.appId}:${focus.country}:${focus.chart}:${days}`, () => fetchAppRank(focus, days), { force });
+
+const POSTING_TTL_MS = 5 * 60_000;
+const postingCache = new Map<string, { at: number; posting: Promise<CloudJobsPostingDetail> }>();
+/**
+ * The page HIRE's evidence row was read from: its title, place, date, pay,
+ * hours and description. Kept a few minutes, so stepping back and forth
+ * through the evidence does not read it again.
+ */
+export function fetchPostingDetail(ticker: string, externalId: string, client: Pick<typeof apiClient, "getCloudJobsPosting"> = apiClient): Promise<CloudJobsPostingDetail> {
+  const key = `${ticker.toUpperCase()}:${externalId}`;
+  const cached = postingCache.get(key);
+  if (cached && Date.now() - cached.at < POSTING_TTL_MS) return cached.posting;
+  const posting = client.getCloudJobsPosting(ticker, { externalId }).then((detail) => {
+    if (!detail || typeof detail.title !== "string" || detail.externalId !== externalId) throw new Error("The server returned an unreadable posting.");
+    return detail;
+  });
+  postingCache.set(key, { at: Date.now(), posting });
+  posting.catch(() => postingCache.delete(key));
+  return posting;
+}