Keep terminal pairing QR codes scannable (#2381)

* fix(pairing): keep terminal QR codes scannable

Prompt framing could wrap dense QR codes and alter long pairing links. Print pairing instructions directly, add the standard quiet zone, and suppress codes that cannot fit without auto-wrapping.

* fix(pairing): contain terminal QR background

packages/cli/src/commands/daemon/pair.ts

@@ -4,6 +4,7 @@ import { generateLocalPairingOffer, loadConfig, resolvePaseoHome } from "@getpas
 import { tryConnectToDaemon } from "../../utils/client.js";
 import { resolveLocalDaemonState, resolveTcpHostFromListen } from "./local-daemon.js";
 import { addJsonOption } from "../../utils/command-options.js";
+import { formatPairingInstructions } from "../../output/pairing.js";
 
 interface PairOptions {
   home?: string;
@@ -97,6 +98,11 @@ function outputPairingResult(
     return;
   }
 
-  const qrBlock = pairing.qr ? `${pairing.qr}\n` : "";
-  process.stdout.write(`\nScan to pair:\n${qrBlock}${pairing.url}\n`);
+  process.stdout.write(
+    formatPairingInstructions({
+      url: pairing.url,
+      qr: pairing.qr,
+      columns: process.stdout.columns,
+    }),
+  );
 }

packages/cli/src/commands/onboard.ts

@@ -18,6 +18,7 @@ import {
   type DaemonStartOptions,
 } from "./daemon/local-daemon.js";
 import { tryConnectToDaemon } from "../utils/client.js";
+import { formatPairingInstructions } from "../output/pairing.js";
 
 interface OnboardOptions extends DaemonStartOptions {
   timeout?: string;
@@ -520,11 +521,13 @@ export async function runOnboard(options: OnboardOptions): Promise<void> {
     return;
   }
 
-  renderNote(
-    pairing.qr ?? "QR is unavailable in this terminal. Use the pairing link below.",
-    "Scan to pair",
+  process.stdout.write(
+    formatPairingInstructions({
+      url: pairing.url,
+      qr: pairing.qr,
+      columns: process.stdout.columns,
+    }),
   );
-  renderNote(pairing.url, "Pairing link");
   printNextSteps(pairing.url, paseoHome, richUi);
   if (richUi) {
     outro("Paseo is ready!");

packages/cli/src/output/pairing.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+import { formatPairingInstructions } from "./pairing.js";
+
+const QR = "\u001b[47m\u001b[30m      \n ████ \n      \u001b[0m";
+const URL = "https://app.paseo.sh/#offer=pairing-offer";
+
+describe("formatPairingInstructions", () => {
+  it("prints the QR and an unmodified pairing-link line when the terminal is wide enough", () => {
+    const output = formatPairingInstructions({ qr: QR, url: URL, columns: 7 });
+
+    expect(output).toContain(QR);
+    expect(output.split("\n")).toContain(URL);
+  });
+
+  it("does not print a QR that would reach the terminal edge", () => {
+    const output = formatPairingInstructions({ qr: QR, url: URL, columns: 6 });
+
+    expect(output).not.toContain(QR);
+    expect(output).toContain("Resize the terminal to at least 7 columns");
+    expect(output.split("\n")).toContain(URL);
+  });
+
+  it("does not risk printing a QR when terminal width is unknown", () => {
+    const output = formatPairingInstructions({ qr: QR, url: URL });
+
+    expect(output).not.toContain(QR);
+    expect(output).toContain("terminal width could not be detected");
+    expect(output.split("\n")).toContain(URL);
+  });
+});

packages/cli/src/output/pairing.ts

@@ -0,0 +1,37 @@
+const ANSI_PATTERN = new RegExp(`${String.fromCharCode(0x1b)}\\[[0-9;]*m`, "g");
+
+interface PairingInstructions {
+  url: string;
+  qr: string | null;
+  columns?: number;
+}
+
+function visibleWidth(value: string): number {
+  return Math.max(
+    ...value
+      .replace(ANSI_PATTERN, "")
+      .split("\n")
+      .map((line) => line.length),
+  );
+}
+
+function formatQr(qr: string | null, columns: number | undefined): string {
+  if (!qr) {
+    return "QR code is unavailable. Use the pairing link below.";
+  }
+
+  if (columns === undefined) {
+    return "QR code not shown because terminal width could not be detected.";
+  }
+
+  const width = visibleWidth(qr);
+  if (columns <= width) {
+    return `QR code not shown. Resize the terminal to at least ${width + 1} columns, then run this command again.`;
+  }
+
+  return qr;
+}
+
+export function formatPairingInstructions({ url, qr, columns }: PairingInstructions): string {
+  return `\nScan to pair:\n${formatQr(qr, columns)}\n\nPairing link:\n${url}\n`;
+}