fix(ui): print next steps before animating the "Next steps" header (#343)

* fix(ui): render next-steps list before sweeping the header highlight

animateHeader redrew only the header line in place, so the 'Next steps' header
shimmered alone for the duration of the animation while the steps printed only
afterward, making it look hung. Print the whole block up front, then step the
cursor back up to sweep the header in place.

Covers clerk link, clerk auth login, clerk init, and clerk deploy next-steps.

* fix(ui): fall back to plain write when block exceeds terminal height

The cursor-up escape that repositions the header only works when the
block fits on screen without scrolling. With a tall next-steps body
(~27 lines for deploy), a short terminal scrolls the buffer and the
cursor-up no longer lands on the header, corrupting the output.

Guard against this by comparing rowsBelow against process.stderr.rows
before entering the animation path.

Author: rafa-thayto

.changeset/next-steps-animation-order.md

@@ -0,0 +1,5 @@
+---
+"clerk": patch
+---
+
+Print the "Next steps" list before sweeping the highlight across its header, so the animation no longer leaves a lone "Next steps" line that looks hung while the steps are hidden.

packages/cli-core/src/commands/deploy/index.ts

@@ -1,7 +1,7 @@
 import type { Program } from "../../cli-program.ts";
 import { deployStatus } from "./status-command.ts";
 import { isAgent } from "../../mode.ts";
-import { isInsideGutter, log } from "../../lib/log.ts";
+import { applyPrefix, isInsideGutter, log } from "../../lib/log.ts";
 import { bold, dim } from "../../lib/color.ts";
 import { animateHeader } from "../../lib/gradient.ts";
 import { bar, intro, outro, pausedOutro, withSpinner } from "../../lib/spinner.ts";
@@ -633,8 +633,8 @@ async function finishDeploy(
     prefix: isInsideGutter() ? `${dim("│")}  ` : "",
     label: "Next steps",
     fallback: bold,
+    body: `${applyPrefix(nextStepsBody(ctx.appId, productionInstanceId))}\n`,
   });
-  log.info(nextStepsBody(ctx.appId, productionInstanceId));
   outro("Success");
 }
 

packages/cli-core/src/lib/gradient.test.ts

@@ -112,6 +112,17 @@ describe("animateHeader (non-interactive)", () => {
     await animateHeader({ prefix: "│  ", label: "Next steps", fallback: bold });
     expect(captured.stderr[0]).toBe(`│  ${bold("Next steps")}\n`);
   });
+
+  test("prints the header and body together in one write", async () => {
+    await animateHeader({
+      prefix: "",
+      label: "Next steps",
+      fallback: bold,
+      body: "   → a\n   → b\n",
+    });
+    expect(captured.stderr).toHaveLength(1);
+    expect(captured.stderr[0]).toBe(`${bold("Next steps")}\n   → a\n   → b\n`);
+  });
 });
 
 describe("animateHeader (interactive gating)", () => {
@@ -145,6 +156,25 @@ describe("animateHeader (interactive gating)", () => {
     expect(captured.err).toContain("\x1b[?25h");
   });
 
+  test("prints the body before sweeping the header so it never looks hung", async () => {
+    await animateHeader({
+      prefix: "",
+      label: "Hi",
+      fallback: bold,
+      body: "   → a\n   → b\n",
+      frames: 2,
+      intervalMs: 1,
+    });
+    const out = captured.err;
+    expect(out).toContain("→ a");
+    expect(out).toContain("→ b");
+    // The body is written before the first in-place header redraw (\r).
+    expect(out.indexOf("→ a")).toBeLessThan(out.indexOf("\r"));
+    // The cursor steps up to the header (1 + 2 body newlines) and back down.
+    expect(out).toContain("\x1b[3A");
+    expect(out).toContain("\x1b[3B");
+  });
+
   test("NO_COLOR disables the animation (plain fallback, no redraw)", async () => {
     process.env.NO_COLOR = "1";
     await run();
@@ -169,4 +199,25 @@ describe("animateHeader (interactive gating)", () => {
     await run();
     expect(captured.err).toContain("\r");
   });
+
+  test("falls back to a plain write when the block is taller than the terminal", async () => {
+    const savedRows = process.stderr.rows;
+    try {
+      Object.defineProperty(process.stderr, "rows", { value: 5, configurable: true });
+      await animateHeader({
+        prefix: "",
+        label: "Hi",
+        fallback: bold,
+        // 5 newlines → rowsBelow = 6, which exceeds rows = 5
+        body: "a\nb\nc\nd\ne\n",
+        frames: 2,
+        intervalMs: 1,
+      });
+      expect(captured.err).not.toContain("\r");
+      expect(captured.err).not.toContain("\x1b[?25l");
+      expect(captured.err).toContain("a");
+    } finally {
+      Object.defineProperty(process.stderr, "rows", { value: savedRows, configurable: true });
+    }
+  });
 });

packages/cli-core/src/lib/gradient.ts

@@ -114,29 +114,63 @@ interface AnimateHeaderOptions {
   prefix: string;
   label: string;
   fallback: (s: string) => string;
+  /**
+   * Text printed beneath the header (e.g. the next-steps list), including its
+   * own trailing newline(s). It is rendered up front so the whole block is on
+   * screen immediately; the highlight then sweeps across the header in place.
+   * Without it, only a lone header animates and looks hung until the caller
+   * prints the rest.
+   */
+  body?: string;
   frames?: number;
   intervalMs?: number;
   write?: (s: string) => void;
 }
 
 export async function animateHeader(options: AnimateHeaderOptions): Promise<void> {
-  const { prefix, label, fallback, frames = 18, intervalMs = 25, write = log.ui } = options;
+  const {
+    prefix,
+    label,
+    fallback,
+    body = "",
+    frames = 18,
+    intervalMs = 25,
+    write = log.ui,
+  } = options;
 
   if (!isInteractive() || colorDisabled()) {
-    write(`${prefix}${fallback(label)}\n`);
+    write(`${prefix}${fallback(label)}\n${body}`);
     return;
   }
 
   const truecolor = supportsTruecolor();
   const span = Math.max(1, frames - 1);
+  // Rows the cursor ends below the header after the block is printed: the
+  // header's own newline plus every newline inside the body.
+  const rowsBelow = 1 + (body.match(/\n/g)?.length ?? 0);
+
+  // The cursor-up escape only lands on the header when the block fits on screen
+  // without scrolling. Fall back to a plain write on short terminals where the
+  // scroll would push the header out of reach.
+  if (process.stderr.rows != null && rowsBelow >= process.stderr.rows) {
+    write(`${prefix}${fallback(label)}\n${body}`);
+    return;
+  }
+
   hideCursor();
   try {
+    // Print the whole block first so the body is visible immediately, then step
+    // back up to the header line and sweep the highlight across it. Only the
+    // header line is rewritten each frame, so the body stays put.
+    write(`${prefix}${shineText(label, { truecolor })}\n${body}`);
+    write(`\x1b[${rowsBelow}A`);
     for (let frame = 0; frame < frames; frame++) {
       const center = -0.3 + (frame / span) * 1.6;
       write(`\r\x1b[K${prefix}${shineText(label, { center, truecolor })}`);
       await sleep(intervalMs);
     }
-    write(`\r\x1b[K${prefix}${shineText(label, { truecolor })}\n`);
+    write(`\r\x1b[K${prefix}${shineText(label, { truecolor })}`);
+    write(`\x1b[${rowsBelow}B\r`);
   } finally {
     showCursor();
   }

packages/cli-core/src/lib/log.ts

@@ -44,7 +44,7 @@ export function isInsideGutter(): boolean {
   return prefixDepth > 0;
 }
 
-function applyPrefix(msg: string): string {
+export function applyPrefix(msg: string): string {
   if (prefixDepth === 0) return msg;
   const bar = dim(S_BAR);
   if (!msg) return bar;

packages/cli-core/src/lib/spinner.ts

@@ -54,16 +54,14 @@ export async function outro(messageOrSteps?: string | readonly string[]) {
   popPrefix();
 
   if (Array.isArray(messageOrSteps)) {
+    const body = `${messageOrSteps.map((step) => `   ${cyan("→")} ${step}`).join("\n")}\n\n`;
     await animateHeader({
       prefix: `${dim(S_BAR_END)}  `,
       label: "Next steps",
       fallback: dim,
+      body,
       write: writeUi,
     });
-    for (const step of messageOrSteps) {
-      writeUi(`   ${cyan("→")} ${step}\n`);
-    }
-    writeUi("\n");
     return;
   }