gloomberb 0.13.2 → 0.14.0

package/src/components/onboarding/account-step/index.tsx

@@ -1,6 +1,5 @@
 import type { RefObject } from "react";
 import type { InputRenderable } from "../../../ui";
-import { AccountChooserPanel } from "./chooser-panel";
 import { AccountFormPanel } from "./form-panel";
 import { AccountQrPanel } from "./qr-panel";
 import { AccountSignedInPanel } from "./signed-in-panel";
@@ -8,9 +7,6 @@ import type { AccountOutcome, AccountSub, AccountSubmitError } from "../../../pl
 
 export interface AccountStepProps {
   sub: AccountSub;
-  choiceIdx: number;
-  onChoiceSelect: (index: number) => void;
-  onChoiceActivate: (index: number) => void;
   email: string;
   password: string;
   fieldIdx: number;
@@ -23,7 +19,6 @@ export interface AccountStepProps {
   onEmailChange: (value: string) => void;
   onPasswordChange: (value: string) => void;
   onFieldFocus: (index: 0 | 1) => void;
-  onSubmitField?: () => void;
   onQrApproved: (email: string) => void;
   height: number;
 }
@@ -37,31 +32,20 @@ export function AccountStep(props: AccountStepProps) {
     return <AccountQrPanel onApproved={props.onQrApproved} height={props.height} />;
   }
 
-  if (props.sub === "signup" || props.sub === "login") {
-    return (
-      <AccountFormPanel
-        mode={props.sub}
-        email={props.email}
-        password={props.password}
-        fieldIdx={props.fieldIdx}
-        editing={props.editing}
-        inputRef={props.inputRef}
-        submitting={props.submitting}
-        submitError={props.submitError}
-        validationError={props.validationError}
-        onEmailChange={props.onEmailChange}
-        onPasswordChange={props.onPasswordChange}
-        onFieldFocus={props.onFieldFocus}
-        onSubmitField={props.onSubmitField}
-      />
-    );
-  }
-
   return (
-    <AccountChooserPanel
-      choiceIdx={props.choiceIdx}
-      onChoiceSelect={props.onChoiceSelect}
-      onChoiceActivate={props.onChoiceActivate}
+    <AccountFormPanel
+      mode={props.sub}
+      email={props.email}
+      password={props.password}
+      fieldIdx={props.fieldIdx}
+      editing={props.editing}
+      inputRef={props.inputRef}
+      submitting={props.submitting}
+      submitError={props.submitError}
+      validationError={props.validationError}
+      onEmailChange={props.onEmailChange}
+      onPasswordChange={props.onPasswordChange}
+      onFieldFocus={props.onFieldFocus}
     />
   );
 }

package/src/components/onboarding/first-run-workspace.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { createDefaultConfig } from "../../types/config";
+import type { TickerRecord } from "../../types/ticker";
+import {
+  FIRST_RUN_PANE_IDS,
+  applyFirstRunLayout,
+  buildFirstRunLayout,
+  planFirstRunWatchlist,
+} from "./first-run-workspace";
+
+function ticker(symbol: string, { held = false, watched = false } = {}): [string, TickerRecord] {
+  return [symbol, {
+    metadata: {
+      ticker: symbol,
+      watchlists: watched ? ["watchlist"] : [],
+      portfolios: held ? ["main"] : [],
+      positions: held ? [{ portfolio: "main", shares: 1, avgCost: 1, currency: "USD", broker: "manual" }] : [],
+    },
+  } as unknown as TickerRecord];
+}
+
+describe("first-run workspace", () => {
+  test("creates the preferred names, capped at seven, skipping holdings", () => {
+    const plan = planFirstRunWatchlist(new Map([ticker("AAPL", { held: true }), ticker("MSFT", { held: true })]), "watchlist", "main");
+    expect(plan.create.map((seed) => seed.ticker)).toEqual(["SPY", "QQQ", "NVDA", "AMZN", "TSLA"]);
+    expect(plan.create[0]).toMatchObject({ watchlists: ["watchlist"], portfolios: [], positions: [], currency: "USD" });
+    expect(plan.update).toEqual([]);
+  });
+
+  test("trims the startup seed to seven and drops holdings from it", () => {
+    // Startup seeds twelve names; the user holds two of them.
+    const seeded = ["AAPL", "MSFT", "GOOGL", "AMZN", "NVDA", "TSLA", "META", "BRK.B", "JPM", "V", "BTC-USD", "ETH-USD"];
+    const tickers = new Map(seeded.map((symbol) => ticker(symbol, { watched: true, held: symbol === "AAPL" || symbol === "NVDA" })));
+    const plan = planFirstRunWatchlist(tickers, "watchlist", "main");
+    expect(plan.create.map((seed) => seed.ticker)).toEqual(["SPY", "QQQ"]);
+    const left = plan.update.filter((entry) => !entry.metadata.watchlists.includes("watchlist")).map((entry) => entry.metadata.ticker).sort();
+    expect(left).toEqual(["AAPL", "BRK.B", "BTC-USD", "ETH-USD", "JPM", "NVDA", "V"]);
+    expect(plan.update.every((entry) => !entry.metadata.watchlists.includes("watchlist"))).toBe(true);
+    const kept = seeded.filter((symbol) => !left.includes(symbol));
+    expect(kept).toEqual(["MSFT", "GOOGL", "AMZN", "TSLA", "META"]);
+    expect(kept.length + plan.create.length).toBe(7);
+  });
+
+  test("lays out heatmap, watchlist, chart and top news, floating a market read", () => {
+    const home = buildFirstRunLayout({
+      symbol: "MSFT",
+      portfolioId: "main",
+      watchlistId: "watchlist",
+      hasPane: (id) => ["portfolio-list", "chart-composer", "news-top", "ticker-news", "world-indices"].includes(id),
+    });
+    const byId = new Map(home.layout.instances.map((instance) => [instance.instanceId, instance]));
+    expect(byId.get(FIRST_RUN_PANE_IDS.heatmap)).toMatchObject({ paneId: "portfolio-list", settings: { viewMode: "grid", collectionScope: "portfolios" } });
+    expect(byId.get(FIRST_RUN_PANE_IDS.watchlist)).toMatchObject({ params: { collectionId: "watchlist" }, settings: { viewMode: "table", collectionScope: "watchlists" } });
+    expect(byId.get(FIRST_RUN_PANE_IDS.chart)).toMatchObject({ paneId: "chart-composer", binding: { kind: "fixed", symbol: "MSFT" } });
+    expect(byId.get(FIRST_RUN_PANE_IDS.news)).toMatchObject({ paneId: "news-top", binding: { kind: "none" } });
+    expect(home.layout.instances.some((instance) => instance.paneId === "ticker-news")).toBe(false);
+    expect(home.layout.floating.map((entry) => entry.instanceId)).toEqual([FIRST_RUN_PANE_IDS.indices]);
+    expect(home.focusedPaneId).toBe(FIRST_RUN_PANE_IDS.chart);
+  });
+
+  test("skips panes the host cannot render instead of leaving placeholders", () => {
+    const home = buildFirstRunLayout({
+      symbol: "MSFT",
+      portfolioId: "main",
+      watchlistId: "watchlist",
+      hasPane: (id) => id === "portfolio-list" || id === "chart-composer",
+    });
+    expect(home.layout.instances.map((instance) => instance.paneId).sort()).toEqual(["chart-composer", "portfolio-list", "portfolio-list"]);
+    expect(home.layout.floating).toEqual([]);
+    expect(home.layout.dockRoot).toMatchObject({ second: { kind: "pane", instanceId: FIRST_RUN_PANE_IDS.chart } });
+  });
+
+  test("replaces Home and makes it the active layout", () => {
+    const config = createDefaultConfig("/tmp/first-run");
+    const home = buildFirstRunLayout({ symbol: "AAPL", portfolioId: "main", watchlistId: "watchlist", hasPane: () => true });
+    const next = applyFirstRunLayout({ ...config, activeLayoutIndex: 2 }, home);
+    expect(next.layouts.map((layout) => layout.name)).toEqual(["Home", "Monitor", "Macro"]);
+    expect(next.layout).toBe(home.layout);
+    expect(next.activeLayoutIndex).toBe(0);
+  });
+});

package/src/components/onboarding/first-run-workspace.ts

@@ -0,0 +1,215 @@
+import {
+  CHART_COMPOSER_PANE_ID,
+  DEFAULT_COLUMNS,
+  DEFAULT_PORTFOLIO_COLUMN_IDS,
+  type AppConfig,
+  type LayoutConfig,
+  type PaneInstanceConfig,
+  type SavedLayout,
+} from "../../types/config";
+import type { TickerMetadata, TickerRecord } from "../../types/ticker";
+
+/**
+ * The watchlist a first run lands with: the two index ETFs and the names most
+ * people recognize, capped so the pane reads at a glance. Startup already
+ * seeds a longer default list; this trims it to the cap and drops anything
+ * the user holds, since holdings live in the heatmap next to it.
+ */
+export const FIRST_RUN_WATCHLIST: ReadonlyArray<Pick<TickerMetadata, "ticker" | "name" | "exchange" | "assetCategory">> = [
+  { ticker: "SPY", name: "SPDR S&P 500 ETF", exchange: "NYSEARCA", assetCategory: "ETF" },
+  { ticker: "QQQ", name: "Invesco QQQ Trust", exchange: "NASDAQ", assetCategory: "ETF" },
+  { ticker: "AAPL", name: "Apple Inc.", exchange: "NASDAQ", assetCategory: "STK" },
+  { ticker: "MSFT", name: "Microsoft Corp.", exchange: "NASDAQ", assetCategory: "STK" },
+  { ticker: "NVDA", name: "NVIDIA Corp.", exchange: "NASDAQ", assetCategory: "STK" },
+  { ticker: "AMZN", name: "Amazon.com Inc.", exchange: "NASDAQ", assetCategory: "STK" },
+  { ticker: "TSLA", name: "Tesla Inc.", exchange: "NASDAQ", assetCategory: "STK" },
+];
+export const FIRST_RUN_WATCHLIST_SIZE = 7;
+
+export const FIRST_RUN_PANE_IDS = {
+  heatmap: "portfolio-list:home-heatmap",
+  watchlist: "portfolio-list:home-watchlist",
+  chart: "chart-composer:home",
+  news: "news-top:home",
+  indices: "world-indices:home",
+  sentiment: "fear-greed:home",
+} as const;
+
+export interface FirstRunWatchlistPlan {
+  /** Tickers that do not exist yet and should be created in the watchlist. */
+  create: TickerMetadata[];
+  /** Existing tickers whose watchlist membership changes (joined or left). */
+  update: TickerRecord[];
+}
+
+/**
+ * What the watchlist should contain: the preferred names first, then whatever
+ * the startup seed left, minus holdings, capped. Returns the writes needed to
+ * get there so the caller persists exactly those.
+ */
+export function planFirstRunWatchlist(
+  tickers: ReadonlyMap<string, TickerRecord>,
+  watchlistId: string,
+  portfolioId: string,
+): FirstRunWatchlistPlan {
+  const held = (symbol: string) => {
+    const ticker = tickers.get(symbol);
+    return !!ticker && (ticker.metadata.portfolios.includes(portfolioId)
+      || ticker.metadata.positions.some((position) => position.portfolio === portfolioId));
+  };
+  const preferred = FIRST_RUN_WATCHLIST.map((seed) => seed.ticker);
+  const seeded = [...tickers.values()]
+    .filter((ticker) => ticker.metadata.watchlists.includes(watchlistId))
+    .map((ticker) => ticker.metadata.ticker);
+  const keep = new Set<string>();
+  for (const symbol of [...preferred, ...seeded]) {
+    if (keep.size >= FIRST_RUN_WATCHLIST_SIZE) break;
+    if (!held(symbol)) keep.add(symbol);
+  }
+
+  const create = FIRST_RUN_WATCHLIST
+    .filter((seed) => keep.has(seed.ticker) && !tickers.has(seed.ticker))
+    .map((seed) => ({
+      ticker: seed.ticker,
+      name: seed.name,
+      exchange: seed.exchange,
+      currency: "USD",
+      assetCategory: seed.assetCategory,
+      portfolios: [],
+      watchlists: [watchlistId],
+      positions: [],
+      custom: {},
+      tags: [],
+    }));
+  const update: TickerRecord[] = [];
+  for (const ticker of tickers.values()) {
+    const symbol = ticker.metadata.ticker;
+    const listed = ticker.metadata.watchlists.includes(watchlistId);
+    if (keep.has(symbol) && !listed) {
+      update.push({ ...ticker, metadata: { ...ticker.metadata, watchlists: [...ticker.metadata.watchlists, watchlistId] } });
+    } else if (!keep.has(symbol) && listed) {
+      update.push({ ...ticker, metadata: { ...ticker.metadata, watchlists: ticker.metadata.watchlists.filter((id) => id !== watchlistId) } });
+    }
+  }
+  return { create, update };
+}
+
+/**
+ * The workspace a first run lands on: the holdings as a mark-to-market
+ * heatmap, a watchlist, the largest position's chart, and the top news wire.
+ * One small floating pane shows that panes are windows. Anything the host
+ * cannot render is left out rather than shown as a placeholder.
+ */
+export function buildFirstRunLayout({
+  symbol,
+  portfolioId,
+  watchlistId,
+  hasPane,
+}: {
+  symbol: string;
+  portfolioId: string;
+  watchlistId: string;
+  hasPane: (paneId: string) => boolean;
+}): SavedLayout {
+  const instances: PaneInstanceConfig[] = [
+    {
+      instanceId: FIRST_RUN_PANE_IDS.heatmap,
+      paneId: "portfolio-list",
+      params: { collectionId: portfolioId },
+      settings: {
+        columnIds: [...DEFAULT_PORTFOLIO_COLUMN_IDS],
+        collectionScope: "portfolios",
+        visibleCollectionIds: [],
+        viewMode: "grid",
+      },
+      binding: { kind: "none" },
+    },
+    {
+      instanceId: FIRST_RUN_PANE_IDS.watchlist,
+      paneId: "portfolio-list",
+      params: { collectionId: watchlistId },
+      settings: {
+        columnIds: DEFAULT_COLUMNS.map((column) => column.id),
+        collectionScope: "watchlists",
+        visibleCollectionIds: [],
+        viewMode: "table",
+      },
+      binding: { kind: "none" },
+    },
+    {
+      instanceId: FIRST_RUN_PANE_IDS.chart,
+      paneId: CHART_COMPOSER_PANE_ID,
+      binding: { kind: "fixed", symbol },
+    },
+  ];
+  // Top news is the curated wire; the per-ticker feed is the fallback when the
+  // wire pane is not registered.
+  const secondary = hasPane("news-top")
+    ? { instanceId: FIRST_RUN_PANE_IDS.news, paneId: "news-top", binding: { kind: "none" as const } }
+    : hasPane("ticker-news")
+      ? { instanceId: "ticker-news:home", paneId: "ticker-news", binding: { kind: "fixed" as const, symbol } }
+      : hasPane("world-indices")
+        ? { instanceId: FIRST_RUN_PANE_IDS.indices, paneId: "world-indices", binding: { kind: "none" as const } }
+        : null;
+  if (secondary) instances.push(secondary);
+
+  // The float is a market read that stands on its own: sentiment when the
+  // plugin is installed, else the indices. The shell clamps floats into the
+  // window, so an off-screen origin lands it in the bottom-right corner on
+  // any size, over the news list rather than the chart.
+  const floatingPaneId = hasPane("fear-greed")
+    ? "fear-greed"
+    : secondary?.paneId !== "world-indices" && hasPane("world-indices")
+      ? "world-indices"
+      : null;
+  const floating: LayoutConfig["floating"] = [];
+  if (floatingPaneId) {
+    const instanceId = floatingPaneId === "fear-greed" ? FIRST_RUN_PANE_IDS.sentiment : FIRST_RUN_PANE_IDS.indices;
+    instances.push({ instanceId, paneId: floatingPaneId, binding: { kind: "none" } });
+    floating.push({ instanceId, x: 9999, y: 9999, width: floatingPaneId === "fear-greed" ? 46 : 60, height: 12 });
+  }
+
+  const layout: LayoutConfig = {
+    dockRoot: {
+      kind: "split",
+      axis: "horizontal",
+      ratio: 0.36,
+      first: {
+        kind: "split",
+        axis: "vertical",
+        ratio: 0.5,
+        first: { kind: "pane", instanceId: FIRST_RUN_PANE_IDS.heatmap },
+        second: { kind: "pane", instanceId: FIRST_RUN_PANE_IDS.watchlist },
+      },
+      second: secondary
+        ? {
+          kind: "split",
+          axis: "vertical",
+          ratio: 0.62,
+          first: { kind: "pane", instanceId: FIRST_RUN_PANE_IDS.chart },
+          second: { kind: "pane", instanceId: secondary.instanceId },
+        }
+        : { kind: "pane", instanceId: FIRST_RUN_PANE_IDS.chart },
+    },
+    instances,
+    floating,
+    detached: [],
+  };
+  return {
+    name: "Home",
+    layout,
+    paneState: {},
+    focusedPaneId: FIRST_RUN_PANE_IDS.chart,
+  };
+}
+
+/** Replaces the Home layout with the first-run workspace and makes it active. */
+export function applyFirstRunLayout(config: AppConfig, home: SavedLayout): AppConfig {
+  const layouts = config.layouts.length > 0 ? [home, ...config.layouts.slice(1)] : [home];
+  return {
+    ...config,
+    layouts,
+    layout: home.layout,
+    activeLayoutIndex: 0,
+  };
+}

package/src/components/onboarding/onboarding-frame.tsx

@@ -5,19 +5,37 @@ import { blendHex } from "../../theme/colors";
 import { useThemeColors } from "../../theme/theme-context";
 import { t } from "../../i18n";
 import { Button, ListView, type ListViewItem } from "../ui";
-import { modalSurfaceStyle } from "../ui/frame";
 import type { ButtonProps } from "../ui/button";
-import { Tabs } from "../ui/tabs";
 import { TITLEBAR_OVERLAY_HEIGHT_PX } from "../layout/titlebar-overlay";
 
+/**
+ * Spacing for the DOM card, in px. The card is a form the user fills in, not
+ * pane chrome, so it does not sit on the terminal cell grid: an 8px rhythm with
+ * one larger break before the footer.
+ */
+export const ONBOARDING_DESKTOP = {
+  padding: "26px 28px 24px",
+  radius: 10,
+  afterProgress: 22,
+  afterTitle: 6,
+  afterHeader: 20,
+  beforeFooter: 24,
+  buttonHeight: "28px",
+} as const;
+
 export function OnboardingModal({
   children,
   width = 66,
   height = 18,
+  desktopWidth,
 }: {
   children: ReactNode;
+  /** Terminal card width in cells. */
   width?: number;
+  /** Terminal card height in rows; the DOM card sizes to its content. */
   height?: number;
+  /** CSS width for the DOM card when a step needs more than the default surface. */
+  desktopWidth?: string;
 }) {
   const colors = useThemeColors();
   const desktop = useUiHost().kind === "desktop-web";
@@ -42,7 +60,19 @@ export function OnboardingModal({
       >
         <Box
           flexDirection="column"
-          style={modalSurfaceStyle(colors)}
+          style={{
+            width: desktopWidth ?? "min(560px, 100%)",
+            height: "auto",
+            maxHeight: "calc(100vh - 88px)",
+            padding: ONBOARDING_DESKTOP.padding,
+            backgroundColor: blendHex(colors.panel, colors.bg, 0.12),
+            borderRadius: ONBOARDING_DESKTOP.radius,
+            // A hairline of light instead of a drawn border: the card reads as
+            // a raised surface, not a box inside a box.
+            boxShadow: `0 24px 64px color-mix(in srgb, ${colors.bg} 55%, transparent), 0 0 0 1px color-mix(in srgb, ${colors.textBright} 5%, transparent)`,
+            boxSizing: "border-box",
+            overflowY: "auto",
+          }}
           data-gloom-role="onboarding-modal"
         >
           {children}
@@ -183,11 +213,14 @@ export function OnboardingTitle({
   step,
   title,
   titlePrefix,
+  titleSuffix,
   description,
 }: {
   step?: string;
   title: string;
   titlePrefix?: ReactNode;
+  /** Short qualifier after the title, e.g. why a struck-through anchor price differs. */
+  titleSuffix?: string;
   description?: string;
 }) {
   const colors = useThemeColors();
@@ -195,11 +228,12 @@ export function OnboardingTitle({
 
   if (desktop) {
     return (
-      <Box flexDirection="column" style={{ marginTop: 14 }}>
+      <Box flexDirection="column" style={{ marginTop: ONBOARDING_DESKTOP.afterProgress }}>
         {step ? (
           <Text
             fg={colors.borderFocused}
             attributes={TextAttributes.BOLD}
+            style={{ fontSize: 11, letterSpacing: 0.6 }}
           >
             {step}
           </Text>
@@ -207,24 +241,25 @@ export function OnboardingTitle({
         <Box
           flexDirection="row"
           alignItems="baseline"
-          gap={titlePrefix ? 1 : 0}
           minWidth={0}
-          style={{ marginTop: step ? 4 : 0 }}
+          style={{ marginTop: step ? 6 : 0, gap: 8 }}
         >
           {titlePrefix}
           <Text
             fg={colors.textBright}
             attributes={TextAttributes.BOLD}
             wrapText
+            style={{ fontSize: 15, lineHeight: "20px" }}
           >
             {title}
           </Text>
+          {titleSuffix ? <Text fg={colors.textMuted}>{titleSuffix}</Text> : null}
         </Box>
         {description ? (
           <Text
             fg={colors.textDim}
             wrapText
-            style={{ marginTop: 6 }}
+            style={{ marginTop: ONBOARDING_DESKTOP.afterTitle }}
           >
             {description}
           </Text>
@@ -240,9 +275,10 @@ export function OnboardingTitle({
           <Text fg={colors.borderFocused} attributes={TextAttributes.BOLD}>{step}</Text>
         </Box>
       ) : null}
-      <Box height={1} flexDirection="row" gap={titlePrefix ? 1 : 0}>
+      <Box height={1} flexDirection="row" gap={titlePrefix || titleSuffix ? 1 : 0}>
         {titlePrefix}
         <Text fg={colors.textBright} attributes={TextAttributes.BOLD}>{title}</Text>
+        {titleSuffix ? <Text fg={colors.textMuted}>{titleSuffix}</Text> : null}
       </Box>
       {description ? (
         <>
@@ -300,34 +336,48 @@ export function OnboardingHeader({
     );
   }
 
+  // Progress, not navigation: three segments, the current one lit, the ones
+  // behind it filled. A filled segment is still a way back.
+  const activeIndex = sections.findIndex((section) => section.id === active);
   return (
-    <Box flexDirection="row" alignItems="center" justifyContent="space-between" minWidth={0}>
-      <Box flexDirection="row" alignItems="center" flexGrow={1} minWidth={0}>
-        {active ? (
-          <Tabs
-            tabs={sections.map((section) => ({
-              label: section.label,
-              value: section.id,
-              disabled: available?.[section.id] === false,
-            }))}
-            activeValue={active}
-            onSelect={(value) => onNavigate?.(value as OnboardingSectionId)}
-            dense
-            variant="underline"
-            keyboardNavigation={false}
-            scrollable={false}
-          />
-        ) : (
-          <Text fg={colors.textMuted} attributes={TextAttributes.BOLD}>
-            {t("GLOOMBERB SETUP")}
-          </Text>
-        )}
+    <Box flexDirection="row" alignItems="flex-start" justifyContent="space-between" minWidth={0}>
+      <Box flexDirection="row" style={{ gap: 10, width: 288, flexShrink: 0 }} data-gloom-role="onboarding-progress">
+        {sections.map((section, index) => {
+          const state = index === activeIndex ? "current" : index < activeIndex ? "done" : "upcoming";
+          const clickable = state !== "current" && available?.[section.id] !== false && !!onNavigate;
+          const bar = state === "current"
+            ? colors.borderFocused
+            : state === "done"
+              ? colors.textDim
+              : blendHex(colors.border, colors.bg, 0.3);
+          const label = state === "current"
+            ? colors.textBright
+            : state === "done"
+              ? colors.text
+              : colors.textMuted;
+          return (
+            <Box
+              key={section.id}
+              flexDirection="column"
+              flexGrow={1}
+              minWidth={0}
+              data-gloom-interactive={clickable ? "true" : undefined}
+              onMouseDown={clickable ? () => onNavigate?.(section.id) : undefined}
+              style={{ gap: 6, cursor: clickable ? "pointer" : "default" }}
+            >
+              <Box style={{ height: 2, borderRadius: 1, backgroundColor: bar }} />
+              <Text fg={label} style={{ fontSize: 11, lineHeight: "14px", fontWeight: state === "current" ? 700 : 500 }}>
+                {section.label}
+              </Text>
+            </Box>
+          );
+        })}
       </Box>
       {showDismiss ? (
-        <Box flexDirection="row" style={{ marginLeft: 12, flexShrink: 0 }}>
+        <Box flexDirection="row" style={{ marginLeft: 12, marginTop: -6, flexShrink: 0 }}>
           <Button
             label={dismissing ? "Closing..." : "Skip setup"}
-            variant="ghost"
+            variant="plain"
             height={1}
             disabled={dismissing || dismissDisabled}
             onPress={onDismiss}
@@ -338,15 +388,38 @@ export function OnboardingHeader({
   );
 }
 
-export function OnboardingActions({ children }: { children: ReactNode }) {
+/**
+ * Footer row. On the DOM renderer the hint sits on the left and the buttons
+ * on the right of the same line, so nothing floats. Terminal steps print
+ * their hints in the body and ignore `hint`.
+ */
+export function OnboardingActions({ children, hint }: { children: ReactNode; hint?: ReactNode }) {
   const desktop = useUiHost().kind === "desktop-web";
+  const colors = useThemeColors();
+  if (desktop) {
+    return (
+      <Box
+        flexDirection="row"
+        justifyContent="space-between"
+        alignItems="center"
+        minWidth={0}
+        style={{ marginTop: ONBOARDING_DESKTOP.beforeFooter, gap: 16 }}
+      >
+        <Box flexDirection="row" alignItems="center" flexGrow={1} minWidth={0} overflow="hidden">
+          {typeof hint === "string" ? <Text fg={colors.textMuted}>{hint}</Text> : hint}
+        </Box>
+        <Box flexDirection="row" alignItems="center" style={{ gap: 8, flexShrink: 0 }}>
+          {children}
+        </Box>
+      </Box>
+    );
+  }
   return (
     <Box
       flexDirection="row"
-      justifyContent={desktop ? "flex-end" : "flex-start"}
+      justifyContent="flex-start"
       alignItems="center"
       gap={1}
-      style={desktop ? { marginTop: 14 } : undefined}
     >
       {children}
     </Box>
@@ -354,7 +427,8 @@ export function OnboardingActions({ children }: { children: ReactNode }) {
 }
 
 export function OnboardingButton(props: ButtonProps) {
-  return <Button {...props} height={props.height ?? 1} />;
+  const desktop = useUiHost().kind === "desktop-web";
+  return <Button {...props} height={props.height ?? (desktop ? ONBOARDING_DESKTOP.buttonHeight : 1)} />;
 }
 
 export function OnboardingChoiceList({