@gloom-sh/terminal 0.19.0 → 0.19.1

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

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { formatActionChords, hasKeybindingCaptureRequest, subscribeKeybindingCapture, useKeybindings } from "../../../app/keybindings";
-import { Notice, Section, SectionHeading, usePaneFooter, usePaneMenuItems, usePaneTabs, type PaneHint, type TableSection } from "../../../components";
+import { Notice, usePaneFooter, usePaneMenuItems, usePaneTabs, type PaneHint, type TableSection } from "../../../components";
 import { t, tf } from "../../../i18n";
 import { colors } from "../../../theme/colors";
 import type { PaneProps } from "../../../types/plugin";
@@ -18,6 +18,7 @@ import { FunctionsTable } from "./functions-table";
 import { KeybindingsEditor } from "./keybindings-editor";
 import { ShortcutTable, type ShortcutTableEntry } from "./shortcut-table";
 import { resolveCommandShortcuts, resolveWindowTemplates } from "./shortcut-model";
+import { badgeColumnWidth } from "./table-cells";
 
 const HELP_TABS = [
   { label: "Basics", value: "basics" },
@@ -47,6 +48,9 @@ const TRY_THESE = [
   { query: "EE TSLA", description: "What analysts expect from Tesla" },
 ] as const;
 
+/** The most of a table its key column takes, however many chips a row carries. */
+const KEY_COLUMN_MAX_SHARE = 0.4;
+
 function HelpPane({ focused, width, height }: PaneProps) {
   const registry = getSharedRegistry();
   const { openCommandBar, showPane, createPaneFromTemplate } = usePluginAppActions();
@@ -83,7 +87,7 @@ function HelpPane({ focused, width, height }: PaneProps) {
   // The UPGRADE line says how long the trial is; the length comes from /pricing.
   const [pricing, setPricing] = useState<CloudPricing | null>(null);
   useEffect(() => {
-    if (activeTabId !== "basics" || pricing) return;
+    if (activeTabId !== "reference" || pricing) return;
     let live = true;
     void apiClient.getCloudPricing()
       .then((next) => {
@@ -131,10 +135,11 @@ function HelpPane({ focused, width, height }: PaneProps) {
   // Each tab's actions. `l` moves between tabs, so layout actions take `a`.
   const tabHints = useMemo<PaneHint[]>(() => {
     if (activeTabId === "basics") {
-      return [
-        { id: "docs", key: "d", label: "ocs", title: "Open Docs", onPress: openDocs },
-        { id: "layout-actions", key: "a", label: " layout actions", title: "Layout Actions", onPress: openLayoutActions },
-      ];
+      return [{ id: "docs", key: "d", label: "ocs", title: "Open Docs", onPress: openDocs }];
+    }
+    // The layout rows are here, so their action is.
+    if (activeTabId === "reference") {
+      return [{ id: "layout-actions", key: "a", label: " layout actions", title: "Layout Actions", onPress: openLayoutActions }];
     }
     if (activeTabId === "functions") {
       return [{ id: "plugins", key: "p", label: "lugins", title: "Manage Plugins", onPress: openPluginManager }];
@@ -192,32 +197,31 @@ function HelpPane({ focused, width, height }: PaneProps) {
     ].filter((item) => hasCode(item.badges[0]!)),
   }], [hasCode]);
 
-  const commandBarSections = useMemo<Array<TableSection<ShortcutTableEntry>>>(() => [{
-    label: "Command Bar",
-    items: [
-      ...(commandBarBadges.length > 0
-        ? [entry("open", commandBarBadges, "Open command mode for actions, pane commands, and typed prefixes.")]
-        : []),
-      ...(tickerSearchBadges.length > 0
-        ? [entry("ticker-search", tickerSearchBadges, "Open ticker search directly.")]
-        : []),
-      entry("des", ["DES", "<ticker>"], "Open security details for a specific ticker."),
-      entry("help-card", ["HELP", "<function>"], "Open a function's help card: what it shows, its keys, how fresh its data is. HELP HELP reaches support."),
-      entry("docs", ["DOCS", "<function>"], "Read the docs and Academy lessons in the app. The ? on a pane opens its entry."),
-      entry("upgrade", ["UPGRADE"], tf("Go Pro for real-time data at gloom.sh/cloud, free for {days} days.", { days: trialDays })),
-      entry("mcp", ["MCP"], "Connect Claude Code, Codex, Cursor or any MCP client to Gloom's research tools."),
-      entry("move", ["Up/Down", "Ctrl+P/N"], "Move through command bar results."),
-      entry("page", ["PageUp/PageDown", "Ctrl+Home/End"], "Jump a page, or to the first or last result."),
-      entry("run", ["Enter", "Shift+Enter"], "Run the selected result or its secondary action."),
-      entry("accept-arg", ["Tab"], "Accept a suggested command argument when one is available."),
-      entry("close", ["Esc", ...tickerSearchBadges.filter((badge) => badge === "`" || badge.includes("+"))], "Close the command bar."),
-      entry("clear", ["Ctrl+U"], "Clear command text."),
-      entry("delete-word", ["Ctrl+W"], "Delete the previous word in command text."),
-      entry("back", ["Backspace"], "Go back from a nested command screen when the query is empty."),
-    ],
-  }], [commandBarBadges, tickerSearchBadges, trialDays]);
-
   const referenceSections = useMemo<Array<TableSection<ShortcutTableEntry>>>(() => [
+    {
+      label: "Command Bar",
+      items: [
+        ...(commandBarBadges.length > 0
+          ? [entry("cmd-open", commandBarBadges, "Open command mode for actions, pane commands, and typed prefixes.")]
+          : []),
+        ...(tickerSearchBadges.length > 0
+          ? [entry("cmd-ticker-search", tickerSearchBadges, "Open ticker search directly.")]
+          : []),
+        entry("cmd-des", ["DES", "<ticker>"], "Open security details for a specific ticker."),
+        entry("cmd-help-card", ["HELP", "<function>"], "Open a function's help card: what it shows, its keys, how fresh its data is. HELP HELP reaches support."),
+        entry("cmd-docs", ["DOCS", "<function>"], "Read the docs and Academy lessons in the app. The ? on a pane opens its entry."),
+        entry("cmd-upgrade", ["UPGRADE"], tf("Go Pro for real-time data at gloom.sh/cloud, free for {days} days.", { days: trialDays })),
+        entry("cmd-mcp", ["MCP"], "Connect Claude Code, Codex, Cursor or any MCP client to Gloom's research tools."),
+        entry("cmd-move", ["Up/Down", "Ctrl+P/N"], "Move through command bar results."),
+        entry("cmd-page", ["PageUp/PageDown", "Ctrl+Home/End"], "Jump a page, or to the first or last result."),
+        entry("cmd-run", ["Enter", "Shift+Enter"], "Run the selected result or its secondary action."),
+        entry("cmd-accept-arg", ["Tab"], "Accept a suggested command argument when one is available."),
+        entry("cmd-close", ["Esc", ...tickerSearchBadges.filter((badge) => badge === "`" || badge.includes("+"))], "Close the command bar."),
+        entry("cmd-clear", ["Ctrl+U"], "Clear command text."),
+        entry("cmd-delete-word", ["Ctrl+W"], "Delete the previous word in command text."),
+        entry("cmd-back", ["Backspace"], "Go back from a nested command screen when the query is empty."),
+      ],
+    },
     {
       label: "Navigation",
       items: [
@@ -235,7 +239,8 @@ function HelpPane({ focused, width, height }: PaneProps) {
         entry("search", ["/"], "Search in the focused pane."),
         entry("sidebar", ["<", ">"], "Narrow or widen the list beside the content, as in MAP and ASKG."),
         entry("warnings", ["!"], "Open the focused pane's data warnings."),
-        entry("notification", [...actionBadges("notification-action"), ...actionBadges("notification-dismiss")], "Run or dismiss the newest notification."),
+        entry("notification", actionBadges("notification-action"), "Run the newest notification."),
+        entry("notification-dismiss", actionBadges("notification-dismiss"), "Dismiss the newest notification."),
       ],
     },
     {
@@ -303,6 +308,14 @@ function HelpPane({ focused, width, height }: PaneProps) {
         entry("close-pane", ["Esc", "Esc"], "Close the focused pane when nothing is being dragged."),
       ],
     },
+    {
+      // Docked panes keep the saved layout and floating ones follow the pointer; the keyboard's way is Window Mode below.
+      label: "Layout",
+      items: [
+        entry("layout-drag", ["Drag"], "Floating panes can be dragged by the title bar and resized from the lower-right corner."),
+        { ...entry("layout-actions", ["LMA"], "Use Layout Actions for split, move, duplicate, close all floating panes, undo, redo, and layout presets."), run: openLayoutActions },
+      ],
+    },
     {
       label: "Window Mode",
       items: [
@@ -320,7 +333,14 @@ function HelpPane({ focused, width, height }: PaneProps) {
         entry("commit", ["Enter", "Esc"], "Commit pending changes or exit window mode."),
       ],
     },
-  ], [askBadges, copyBadges, functionHelpBadges, pasteBadges, windowMoveBadges, windowResizeBadges]);
+  ], [askBadges, commandBarBadges, copyBadges, functionHelpBadges, openLayoutActions, pasteBadges, tickerSearchBadges, trialDays, windowMoveBadges, windowResizeBadges]);
+
+  // One key column for every key table in Help, wide enough for the longest group of chips, so the descriptions
+  // line up from table to table. A narrow pane caps it, and a row past the cap shows the chips that fit whole.
+  const keyColumnWidth = useMemo(() => badgeColumnWidth(
+    [...trySections, ...startSections, ...referenceSections].flatMap((section) => section.items.map((item) => item.badges)),
+    { min: 8, max: Math.max(8, Math.floor(width * KEY_COLUMN_MAX_SHARE)) },
+  ), [referenceSections, startSections, trySections, width]);
 
   const renderContent = () => {
     switch (activeTabId) {
@@ -339,38 +359,19 @@ function HelpPane({ focused, width, height }: PaneProps) {
           <>
             {trySections.length > 0 && (
               <Box marginBottom={1}>
-                <ShortcutTable sections={trySections} width={bodyWidth} keyLabel="TYPE" descriptionLabel="OPENS" />
+                <ShortcutTable sections={trySections} width={bodyWidth} keyWidth={keyColumnWidth} keyLabel="TYPE" descriptionLabel="OPENS" />
               </Box>
             )}
 
-            <Box flexDirection="column" gap={1}>
-              <SectionHeading title="How To Use Gloom" />
-              <Box flexDirection="column">
-                <Text fg={colors.textDim} wrapText>{t("Click anything to use it; the keys shown beside actions are shortcuts.")}</Text>
-                <Text fg={colors.textDim} wrapText>
-                  {commandBarBadges[0]
-                    ? tf("Not sure of a code? Click the search bar at the top, or press {key}, and type what you want in plain words, like \"top news\". The Functions tab lists everything.", { key: commandBarBadges[0] })
-                    : t("Not sure of a code? Click the search bar at the top and type what you want in plain words, like \"top news\". The Functions tab lists everything.")}
-                </Text>
-              </Box>
-            </Box>
+            <Text fg={colors.textDim} wrapText>
+              {commandBarBadges[0]
+                ? tf("Not sure of a code? Click the search bar at the top, or press {key}, and type what you want in plain words, like \"top news\". The Functions tab lists everything.", { key: commandBarBadges[0] })
+                : t("Not sure of a code? Click the search bar at the top and type what you want in plain words, like \"top news\". The Functions tab lists everything.")}
+            </Text>
 
             <Box marginTop={1}>
-              <ShortcutTable sections={startSections} width={bodyWidth} />
+              <ShortcutTable sections={startSections} width={bodyWidth} keyWidth={keyColumnWidth} />
             </Box>
-
-            <Box marginTop={1}>
-              <ShortcutTable sections={commandBarSections} width={bodyWidth} />
-            </Box>
-
-            <Section title="Layout Basics">
-              <Text fg={colors.text}>{t("Docked panes stay in the saved layout.")}</Text>
-              <Text fg={colors.text} wrapText>{t("Floating panes can be dragged by the title bar and resized from the lower-right corner.")}</Text>
-              {windowMoveBadges[0] && windowResizeBadges[0] && (
-                <Text fg={colors.text} wrapText>{tf("From the keyboard, {move} moves the focused window and {resize} resizes it.", { move: windowMoveBadges[0], resize: windowResizeBadges[0] })}</Text>
-              )}
-              <Text fg={colors.text} wrapText>{t("Use Layout Actions for split, move, duplicate, close all floating panes, undo, redo, and layout presets.")}</Text>
-            </Section>
           </>
         );
     }
@@ -396,6 +397,7 @@ function HelpPane({ focused, width, height }: PaneProps) {
         <ShortcutTable
           sections={referenceSections}
           width={width}
+          keyWidth={keyColumnWidth}
           height={contentHeight}
           after={(
             <Box paddingX={1} flexShrink={0}>

package/src/plugins/builtin/help/shortcut-table.tsx

@@ -22,7 +22,7 @@ import {
 import { t } from "../../../i18n";
 import { useThemeColors } from "../../../theme/theme-context";
 import { Box, useUiCapabilities } from "../../../ui";
-import { badgeCell, badgeColumnWidth } from "./table-cells";
+import { badgeCell } from "./table-cells";
 
 export interface ShortcutTableEntry {
   id: string;
@@ -38,6 +38,7 @@ type ShortcutRow = SectionedRow<ShortcutTableEntry>;
 export function ShortcutTable({
   sections,
   width,
+  keyWidth,
   height: fillHeight,
   after,
   keyLabel = "KEY",
@@ -46,6 +47,8 @@ export function ShortcutTable({
   sections: ReadonlyArray<TableSection<ShortcutTableEntry>>;
   /** Content width available inside the tab body. */
   width: number;
+  /** The key column's width, one for every table in Help so their descriptions line up. */
+  keyWidth: number;
   /** Fill this many rows and scroll, instead of growing to fit every row. */
   height?: number;
   /** Sits under a full-height table inside the same frame. */
@@ -59,10 +62,6 @@ export function ShortcutTable({
     () => buildSectionedRows(sections, (entry) => entry.id),
     [sections],
   );
-  const keyWidth = useMemo(
-    () => badgeColumnWidth(rows.filter(isSectionedItemRow).map((row) => row.item.badges), { min: 8, max: 24 }),
-    [rows],
-  );
   const columns = useMemo<ShortcutColumn[]>(() => [
     { id: "key", label: keyLabel, width: keyWidth, align: "left" },
     { id: "description", label: descriptionLabel, width: 20, align: "left", flexGrow: 1 },
@@ -72,7 +71,7 @@ export function ShortcutTable({
     if (!isSectionedItemRow(row)) return EMPTY_TABLE_CELL;
     const run = row.item.run;
     const cell: DataTableCell = column.id === "key"
-      ? badgeCell(row.item.badges, column.width)
+      ? badgeCell(row.item.badges, column.width, { wholeOnly: true })
       : { text: t(row.item.description), color: colors.text };
     if (!run) return cell;
     return {

package/src/plugins/builtin/help/table-cells.tsx

@@ -31,10 +31,21 @@ export function badgeColumnWidth(
   return Math.max(min, Math.min(max, widest));
 }
 
+/**
+ * The chips of a group that fit a column whole, in order. A chip that would be
+ * cut ("Ctrl+Hor") is left out instead, so what shows is always a real key; the
+ * first chip stays whatever the width.
+ */
+export function wholeBadges(labels: readonly string[], width: number): readonly string[] {
+  let count = Math.min(1, labels.length);
+  while (count < labels.length && badgeGroupWidth(labels.slice(0, count + 1)) <= width) count += 1;
+  return labels.slice(0, count);
+}
+
 export function badgeCell(
   labels: readonly string[],
   width: number,
-  options: { tone?: "neutral" | "accent"; emptyLabel?: string; emptyColor?: string } = {},
+  options: { tone?: "neutral" | "accent"; emptyLabel?: string; emptyColor?: string; wholeOnly?: boolean } = {},
 ): DataTableCell {
   if (labels.length === 0) {
     return options.emptyLabel
@@ -45,7 +56,7 @@ export function badgeCell(
     text: labels.join(" "),
     content: (
       <Box flexDirection="row" gap={BADGE_GAP} width={width} height={1} overflow="hidden">
-        {labels.map((label, index) => (
+        {(options.wholeOnly ? wholeBadges(labels, width) : labels).map((label, index) => (
           <Badge key={`${label}:${index}`} label={label} variant="solid" tone={options.tone ?? "neutral"} />
         ))}
       </Box>

package/src/plugins/builtin/holders/beneficial-client.ts

@@ -11,6 +11,7 @@ import { listingAbroad, type IssuerListingParams } from "../../../api-client/pat
 import { createPluginCache } from "../../../data/plugin-cache";
 import { secListingKey } from "../../../utils/sec";
 import { finiteOrNull, recordOrNull } from "../../../utils/guards";
+import { readCompanyFrom } from "../../../types/company-from";
 import { cachedCloudResource, loadCloudResource, type CloudResource } from "../shared/cloud-resource";
 import { CLOUD_SESSION_REQUIRED } from "../shared/research-cloud-session";
 
@@ -110,8 +111,11 @@ function normalizeBeneficialOwnersPayload(value: unknown, ticker: string): Benef
   if (!raw || !Array.isArray(raw.owners)) throw new Error("The server returned an invalid 13D/13G list");
   const coverage = recordOrNull(raw.coverage);
   const nextOffset = finiteOrNull(raw.nextOffset);
+  const companyFrom = readCompanyFrom(raw.companyFrom);
+  const { companyFrom: _unread, ...rest } = raw;
   return {
-    ...raw,
+    ...rest,
+    ...(companyFrom ? { companyFrom } : {}),
     ticker: text(raw.ticker) ?? ticker,
     cik: cikOrNull(raw.cik) ?? "",
     companyName: text(raw.companyName) ?? "",

package/src/plugins/builtin/holders/beneficial-view.tsx

@@ -9,6 +9,7 @@ import {
   type DataTableCell,
   type DataTableKeyEvent,
 } from "../../../components";
+import { useCompanyDataFooter } from "../../../components/layout/pane/status-footer";
 import { handleRefreshKey, loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
 import type { IssuerListingParams } from "../../../api-client/paths";
 import { useAsyncResource } from "../../../react/async-resource";
@@ -233,6 +234,8 @@ export function BeneficialOwnersView({
     focused,
     title: "13D/13G coverage",
   });
+  // A foreign line's owners are its company's, read from the home line.
+  useCompanyDataFooter(payload?.companyFrom);
   usePaneFooter("holders-13dg", () => ({
     info: [
       ...(payload?.asOf ? [{ id: "as-of", parts: [{ text: `as of ${payload.asOf.slice(0, 10)}`, tone: "muted" as const }] }] : []),

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

@@ -7,7 +7,7 @@ import { loadHolderSnapshot } from "./client";
 import { holderValueCurrency } from "./format";
 import { logFailure } from "../../../utils/log-failure";
 import type { HolderData } from "../../../types/financials";
-import { SEC_FILINGS } from "../shared/report-freshness";
+import { SEC_FILING_ROWS, SEC_FILINGS } from "../shared/report-freshness";
 import type { BeneficialOwnersPayload } from "../../../api-client/beneficial-owners";
 import { fetchBeneficialOwners, type BeneficialOwnersRequest } from "./beneficial-client";
 import { resolveHeadlessInstrument, resolveHeadlessIssuerListing } from "../shared/headless-market-data";
@@ -34,6 +34,7 @@ import {
 } from "./report-rows";
 import { REPORT_ROWS } from "../shared/headless-options";
 import { fundHoldersAnswer } from "./fund-holders";
+import { companyDataNotes } from "../../../types/company-from";
 import {
   HOLDER_ROWS_MAX,
   indexedHoldersPartialNote,
@@ -197,7 +198,7 @@ export function createHoldersHeadless(
           rows: limited,
           // Reports that could not be read this time are missing from the rows.
           complete: beneficialListComplete(payload),
-          freshness: { ...SEC_FILINGS, basis: "13D/13G filings", observedKey: "filingDate" },
+          freshness: { ...SEC_FILING_ROWS, basis: "13D/13G filings" },
           metadata: {
             symbol: payload.ticker || symbol,
             name: payload.companyName || null,
@@ -212,6 +213,7 @@ export function createHoldersHeadless(
               [payload.companyName || symbol, ...beneficialListFacts(payload, form, rows.length, history)].join(" · "),
               ...(legend ? [legend] : []),
               ...beneficialCoverageNotices(payload.coverage),
+              ...companyDataNotes(payload.companyFrom),
             ],
             returned: limited.length,
             total: rows.length,

package/src/plugins/builtin/holders/pane.tsx

@@ -12,6 +12,7 @@ import {
   type DataTableKeyEvent,
   type PageRequest,
 } from "../../../components";
+import { useCompanyDataFooter } from "../../../components/layout/pane/status-footer";
 import { handleRefreshKey, loadingErrorFooterInfo } from "../../../components/data-table/table-pane";
 import { useAsyncResource } from "../../../react/async-resource";
 import { useShortcut } from "../../../react/input";
@@ -321,6 +322,8 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
     }
   }, [currency, fundMatches, marketCap]);
 
+  // Holders read from the company's home line say whose; the SEC index's rows are the listing's own.
+  useCompanyDataFooter(indexed ? null : listData?.companyFrom, viewMode !== "13dg");
   // The 13D/G tab registers its own footer.
   usePaneFooter("holders", () => {
     if (viewMode === "13dg") return null;

package/src/plugins/builtin/holders/report-rows.ts

@@ -25,6 +25,7 @@ import {
 import { HOLDER_ROWS_MAX } from "./index-holders";
 import { buildRows, DEFAULT_SORT, sortRows } from "./table-model";
 import type { HolderColumnId, SortPreference } from "./types";
+import { companyDataNotes } from "../../../types/company-from";
 
 /**
  * A holder as `holders` and `fn HDS` report it; the keys are the JSON
@@ -231,7 +232,9 @@ export function holderReportNotices({
       ? `The source lists its ${reported} largest holders; fn 13F ${requested} lists all ${total.toLocaleString("en-US")}.`
       : null;
   return {
-    notices: [header, basis, cut, positionsBasis, holderShareBasisNote(data, shown), unvaluedHoldersNote(shown, sort)]
+    notices: [header, basis, cut, positionsBasis, holderShareBasisNote(data, shown), unvaluedHoldersNote(shown, sort),
+      // The SEC index's rows are the listing's own; the source's, its company's home line's when it says so.
+      ...(indexed ? [] : companyDataNotes(data.companyFrom))]
       .filter((line): line is string => !!line),
     valueBasis,
     positionsBasis,

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

@@ -20,7 +20,7 @@ import {
 } from "./model";
 import { isAmendedInsiderFiling, relevantInsiderAmendments } from "./amendments";
 import { formatInsiderName } from "./display";
-import { SEC_FILINGS } from "../shared/report-freshness";
+import { SEC_FILING_ROWS } from "../shared/report-freshness";
 import { resolveHeadlessInstrument, resolveHeadlessIssuerListing } from "../shared/headless-market-data";
 import { noSecReportsNotice } from "../../../utils/sec";
 import { parsePublicTickerKey } from "../../../utils/exchanges";
@@ -329,7 +329,7 @@ export function createInsiderHeadless(
 ): HeadlessPaneDefinition<"rows"> {
   return {
     shape: "rows",
-    freshness: { ...SEC_FILINGS, basis: "Form 4 filings", observedKey: "filingDate" },
+    freshness: { ...SEC_FILING_ROWS, basis: "Form 4 filings" },
     argument: {
       kind: "ticker",
       optional: true,

package/src/plugins/builtin/ipo-calendar/client.ts

@@ -1,5 +1,5 @@
 import { apiClient } from "../../../api-client";
-import type { IpoCalendarParams, IpoCalendarPayload, IpoDeal, IpoSourceHealth } from "../../../api-client/ipo";
+import type { IpoCalendarParams, IpoCalendarPayload, IpoDeal, IpoLockup, IpoSourceHealth } from "../../../api-client/ipo";
 import type { HeadlessPaneApiClient } from "../../../types/plugin";
 import { createPluginCache } from "../../../data/plugin-cache";
 import { cachedCloudResource, loadCloudResource, unavailableOnServer, type CloudResource } from "../shared/cloud-resource";
@@ -45,6 +45,21 @@ function validDeal(deal: IpoDeal): boolean {
     && validFirstDay(deal.firstDay);
 }
 
+function validLockup(value: unknown): value is IpoLockup {
+  const lockup = value as IpoLockup | null;
+  return !!lockup && typeof lockup === "object" && typeof lockup.endsOn === "string" && dayOrNull(lockup.endsOn)
+    && typeof lockup.days === "number" && Number.isFinite(lockup.days) && lockup.days > 0
+    && (lockup.basis === "prospectus" || lockup.basis === "typical")
+    && dayOrNull(lockup.prospectusDate ?? null) && textOrNull(lockup.prospectusUrl ?? null);
+}
+
+/** A lock-up estimate the client cannot read is left off its deal; the deal stays. */
+function withReadableLockup(deal: IpoDeal): IpoDeal {
+  if (deal.lockup == null || validLockup(deal.lockup)) return deal;
+  const { lockup: _unreadable, ...rest } = deal;
+  return rest;
+}
+
 function validSource(source: IpoSourceHealth): boolean {
   return !!source && text(source.id) && Array.isArray(source.mics) && source.mics.every(text)
     && typeof source.ok === "boolean" && textOrNull(source.asOf);
@@ -61,7 +76,8 @@ export function validateIpoCalendar(data: IpoCalendarPayload): IpoCalendarPayloa
   }
   return {
     asOf: data.asOf,
-    deals: data.deals.filter(validDeal).map((deal) => (REGIONS.has(deal.region) ? deal : { ...deal, region: "other" })),
+    deals: data.deals.filter(validDeal).map(withReadableLockup)
+      .map((deal) => (REGIONS.has(deal.region) ? deal : { ...deal, region: "other" })),
     sources: data.sources.filter(validSource),
   };
 }

package/src/plugins/builtin/ipo-calendar/headless.ts

@@ -9,11 +9,13 @@ import { fetchIpoCalendar } from "./client";
 import {
   calendarDate,
   filterIpoDeals,
+  formatIpoLockupEnd,
   formatIpoPrice,
   formatIpoReturn,
   formatIpoSize,
   IPO_STATUSES,
   ipoBoardStatus,
+  ipoKeyword,
   isIpoTab,
   marketsBehind,
   marketsBehindText,
@@ -21,7 +23,10 @@ import {
   DEFAULT_IPO_SORT,
   type IpoTab,
 } from "./model";
+import { ipoDetailSentences, loadIpoLockupNews, type IpoLockupStory } from "./listing-ipo";
 import { REPORT_FILTER, REPORT_ROWS } from "../shared/headless-options";
+import { DATE_OPTION_EXAMPLES, isoDateOption } from "../../../utils/calendar-date";
+import { logFailure } from "../../../utils/log-failure";
 
 const COLUMNS: HeadlessPaneColumn[] = [
   { key: "ticker", header: "Ticker" },
@@ -33,6 +38,8 @@ const COLUMNS: HeadlessPaneColumn[] = [
   { key: "price", header: "Price", align: "right" },
   { key: "offerSizeUsd", header: "Size", align: "right", format: (value) => formatIpoSize(value as number | null) },
   { key: "firstDayReturn", header: "Return", align: "right", format: (value) => formatIpoReturn(value as number | null) },
+  // A US IPO's estimated lock-up end: "~2026-11-02".
+  { key: "lockupEnds", header: "Lockup ends", format: (value) => formatIpoLockupEnd(typeof value === "string" ? value : null) },
 ];
 
 type StatusOption = IpoStatus | "all";
@@ -68,7 +75,7 @@ function toRow(deal: IpoDeal, now: Date) {
     status: ipoBoardStatus(deal, now),
     listingType: deal.listingType,
     currency: deal.currency,
-    price: formatIpoPrice(deal),
+    price: formatIpoPrice(deal, { full: true }),
     priceLow: deal.priceLow,
     priceHigh: deal.priceHigh,
     offerPrice: deal.offerPrice,
@@ -78,26 +85,60 @@ function toRow(deal: IpoDeal, now: Date) {
     firstDayClose: deal.firstDay?.close ?? null,
     firstDayReturn: deal.firstDay?.returnPct ?? null,
     filedDate: deal.filedDate,
+    lockupEnds: deal.lockup?.endsOn ?? null,
+    lockupBasis: deal.lockup?.basis ?? null,
+    prospectusDate: deal.lockup?.prospectusDate ?? null,
   };
 }
 
-function projectIpoCalendarHeadless(payload: IpoCalendarPayload, args: HeadlessPaneLoadArgs): HeadlessRowsResult {
+/** One deal found: its IPO in words, as `ticker` gives it, with its price now and its lock-up news. */
+interface IpoDealDetail {
+  price: number | null;
+  news: IpoLockupStory[];
+}
+
+/** Lock-up estimates soonest first, then the ones that have ended, latest first. */
+function byLockupEnd(deals: readonly IpoDeal[], now: Date): IpoDeal[] {
+  const today = now.toISOString().slice(0, 10);
+  const rank = (deal: IpoDeal) => (deal.lockup!.endsOn >= today ? 0 : 1);
+  return [...deals].sort((a, b) => rank(a) - rank(b)
+    || (rank(a) === 0 ? a.lockup!.endsOn.localeCompare(b.lockup!.endsOn) : b.lockup!.endsOn.localeCompare(a.lockup!.endsOn))
+    || a.id.localeCompare(b.id));
+}
+
+/** The most rows `--limit` lists. */
+const MAX_ROWS = 500;
+
+const SPAC_NOTE = "A SPAC's merger with its target (de-SPAC) is no IPO, so the calendar lists the SPACs' own IPOs.";
+
+export function projectIpoCalendarHeadless(
+  payload: IpoCalendarPayload,
+  args: HeadlessPaneLoadArgs,
+  detail: IpoDealDetail | null = null,
+  now = new Date(),
+): HeadlessRowsResult {
   const query = typeof args.argument === "string" ? args.argument.trim() : "";
   const region = regionOption(args);
   const status = statusOption(args);
   const limit = Number(args.options.limit ?? 50);
-  const now = new Date();
-  const matching = sortIpoDeals(
-    filterIpoDeals(payload.deals, region, query, now).filter((deal) => status === "all" || deal.status === status),
-    DEFAULT_IPO_SORT,
-    now,
-  );
+  const keyword = ipoKeyword(query);
+  const found = filterIpoDeals(payload.deals, region, query, now).filter((deal) => status === "all" || deal.status === status);
+  const matching = keyword === "lockup" ? byLockupEnd(found, now) : sortIpoDeals(found, DEFAULT_IPO_SORT, now);
   const rows = matching.slice(0, limit).map((deal) => toRow(deal, now));
   const behind = marketsBehindText(marketsBehind(payload.sources, region, payload.deals));
+  const single = matching.length === 1 && query && !keyword ? matching[0]! : null;
+  const notes = [
+    ...rows.length < matching.length
+      ? [`Showing ${rows.length} of ${matching.length} deals; --limit ${Math.min(matching.length, MAX_ROWS)} lists ${matching.length <= MAX_ROWS ? "them all" : "more"}.`]
+      : [],
+    ...single ? ipoDetailSentences(single, detail?.price ?? null, detail?.news ?? [], now) : [],
+    ...keyword === "spac" || keyword === "de-spac" ? [SPAC_NOTE] : [],
+  ];
   return {
     columns: COLUMNS,
     rows,
     ...(behind ? { errors: [behind] } : {}),
+    ...(notes.length ? { notes } : {}),
     metadata: {
       asOf: payload.asOf,
       total: matching.length,
@@ -149,7 +190,15 @@ export const ipoCalendarHeadless: HeadlessPaneDefinition<"rows"> = {
       type: "integer",
       defaultValue: 50,
       minimum: 1,
-      maximum: 500,
+      maximum: MAX_ROWS,
+    },
+    {
+      key: "from",
+      type: "string",
+      placeholder: "date",
+      description: `First listing date, as ${DATE_OPTION_EXAMPLES}; the calendar keeps a year of listings.`,
+      example: "--from 2025-11-01",
+      normalize: (value) => isoDateOption(value, "from"),
     },
   ],
   columns: COLUMNS,
@@ -164,7 +213,22 @@ export const ipoCalendarHeadless: HeadlessPaneDefinition<"rows"> = {
   async load(args, ctx) {
     // The default window has no filed or withdrawn deals, so a stage is asked for by name.
     const status = statusOption(args);
-    const params = status === "all" ? {} : { status };
-    return projectIpoCalendarHeadless(await fetchIpoCalendar(ctx.apiClient, ctx.signal, params), args);
+    const from = typeof args.options.from === "string" && args.options.from ? args.options.from : undefined;
+    const params = { ...(status === "all" ? {} : { status }), ...(from ? { from } : {}) };
+    const payload = await fetchIpoCalendar(ctx.apiClient, ctx.signal, params);
+    const projected = projectIpoCalendarHeadless(payload, args);
+    // One deal found: its price now and its lock-up news, which never fail the report.
+    const query = typeof args.argument === "string" ? args.argument.trim() : "";
+    const matched = projected.rows.length === 1 && query && !ipoKeyword(query)
+      ? payload.deals.find((deal) => deal.id === projected.rows[0]!.id) : undefined;
+    if (!matched?.symbol) return projected;
+    const [price, news] = await Promise.all([
+      matched.status === "listed"
+        ? ctx.marketData.getQuote(matched.symbol, matched.exchange ?? undefined).then((quote) => quote.price ?? null,
+          logFailure("plugins.ipo-calendar", "Load the price of an IPO failed", null))
+        : Promise.resolve(null),
+      loadIpoLockupNews(ctx.apiClient, matched).catch(logFailure("plugins.ipo-calendar", "Load an IPO's lock-up news failed", [] as IpoLockupStory[])),
+    ]);
+    return projectIpoCalendarHeadless(payload, args, { price, news });
   },
 };