fix(ui): prepare history reviews before terminal handoff

.changeset/flicker-free-history-review.md

@@ -0,0 +1,5 @@
+---
+"hunkdiff": patch
+---
+
+Keep the themed history loading screen visible until a selected commit review is ready to claim the terminal.

src/app/startup.test.ts

@@ -749,6 +749,35 @@ describe("startup planning", () => {
     expect(opened).toBe(1);
   });
 
+  test("inherits handoff theme mode without querying the parent-owned terminal", async () => {
+    const cliInput: CliInput = {
+      kind: "show",
+      ref: "opaque:id",
+      options: { theme: "auto" },
+    };
+    let detected = 0;
+
+    const plan = await prepareStartupPlan(["bun", "hunk", "show", "opaque:id"], {
+      parseCliImpl: async () => cliInput as ParsedCliInput,
+      resolveRuntimeCliInputImpl: (input) => input,
+      resolveConfiguredCliInputImpl: (input) => createTestConfigResolution(input),
+      loadAppBootstrapImpl: async (input) => createBootstrap(input),
+      detectTerminalThemeModeFromBackgroundImpl: async () => {
+        detected += 1;
+        return "light";
+      },
+      stdinIsTTY: true,
+      stdoutIsTTY: true,
+      env: {
+        HUNK_TERMINAL_HANDOFF: "1",
+        HUNK_TERMINAL_HANDOFF_THEME_MODE: "dark",
+      },
+    });
+
+    expect(plan).toMatchObject({ kind: "app", bootstrap: { initialThemeMode: "dark" } });
+    expect(detected).toBe(0);
+  });
+
   test("opens the controlling terminal for piped patch startup", async () => {
     const cliInput: CliInput = {
       kind: "patch",

src/app/startup.ts

@@ -5,6 +5,7 @@ import { resolveConfiguredCliInput } from "../core/run/config";
 import { HunkUserError } from "../core/run/errors";
 import type { loadAppBootstrap } from "../core/changeset/loaders";
 import { looksLikePatchInput } from "../core/process/pager";
+import { terminalHandoffThemeMode } from "../core/process/terminalHandoff";
 import { sanitizeTerminalText } from "../lib/terminalText";
 import { detectTerminalThemeModeFromBackground } from "../core/theme/detection";
 import {
@@ -543,8 +544,10 @@ export async function prepareStartupPlan(
     controllingTerminal = openControllingTerminalImpl();
   }
 
-  let initialThemeMode: AppBootstrap["initialThemeMode"];
-  if (cliInput.options.theme === "auto" && stdoutIsTTY) {
+  // A handoff child inherits the parent's detected mode so bootstrap never queries a terminal
+  // whose input and renderer are still exclusively owned by the history process.
+  let initialThemeMode: AppBootstrap["initialThemeMode"] = terminalHandoffThemeMode(env);
+  if (!initialThemeMode && cliInput.options.theme === "auto" && stdoutIsTTY) {
     const themeInput = controllingTerminal?.stdin ?? (stdinIsTTY ? process.stdin : null);
     if (themeInput) {
       initialThemeMode =

src/core/process/terminalHandoff.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import {
+  hasTerminalHandoff,
+  parseTerminalHandoffMessage,
+  terminalHandoffEnv,
+  terminalHandoffMessage,
+  terminalHandoffThemeMode,
+} from "./terminalHandoff";
+
+describe("terminal handoff protocol", () => {
+  test("uses a private marker and inherits only a valid terminal mode", () => {
+    const env = terminalHandoffEnv({ PATH: "/bin" }, "dark");
+    expect(hasTerminalHandoff(env)).toBe(true);
+    expect(terminalHandoffThemeMode(env)).toBe("dark");
+    expect(
+      terminalHandoffThemeMode({
+        HUNK_TERMINAL_HANDOFF: "1",
+        HUNK_TERMINAL_HANDOFF_THEME_MODE: "blue",
+      }),
+    ).toBeUndefined();
+    expect(terminalHandoffThemeMode({ HUNK_TERMINAL_HANDOFF_THEME_MODE: "light" })).toBeUndefined();
+  });
+
+  test("accepts only versioned bounded messages", () => {
+    expect(parseTerminalHandoffMessage(terminalHandoffMessage("ready"))).toEqual({
+      protocol: "hunk-terminal-handoff-v1",
+      kind: "ready",
+    });
+    expect(parseTerminalHandoffMessage({ protocol: "wrong", kind: "ready" })).toBeUndefined();
+    expect(
+      parseTerminalHandoffMessage({ protocol: "hunk-terminal-handoff-v1", kind: "other" }),
+    ).toBeUndefined();
+    expect(
+      parseTerminalHandoffMessage({
+        protocol: "hunk-terminal-handoff-v1",
+        kind: "failed",
+        message: "x".repeat(3_000),
+      }),
+    ).toEqual({
+      protocol: "hunk-terminal-handoff-v1",
+      kind: "failed",
+      message: "x".repeat(2_000),
+    });
+  });
+});

src/core/process/terminalHandoff.ts

@@ -0,0 +1,116 @@
+const HANDOFF_ENV = "HUNK_TERMINAL_HANDOFF";
+const HANDOFF_THEME_MODE_ENV = "HUNK_TERMINAL_HANDOFF_THEME_MODE";
+const PROTOCOL = "hunk-terminal-handoff-v1";
+
+export type TerminalHandoffMessage =
+  | { protocol: typeof PROTOCOL; kind: "ready" }
+  | { protocol: typeof PROTOCOL; kind: "release" }
+  | { protocol: typeof PROTOCOL; kind: "failed"; message: string };
+
+/** Return whether this process was launched for a coordinated terminal handoff. */
+export function hasTerminalHandoff(env: NodeJS.ProcessEnv = process.env) {
+  return env[HANDOFF_ENV] === "1";
+}
+
+/** Read the parent's already-detected terminal mode without querying the owned terminal again. */
+export function terminalHandoffThemeMode(
+  env: NodeJS.ProcessEnv = process.env,
+): "dark" | "light" | undefined {
+  if (!hasTerminalHandoff(env)) return undefined;
+  const value = env[HANDOFF_THEME_MODE_ENV];
+  return value === "dark" || value === "light" ? value : undefined;
+}
+
+/** Add the private one-shot handoff marker and terminal mode to a child environment. */
+export function terminalHandoffEnv(
+  env: NodeJS.ProcessEnv,
+  themeMode: "dark" | "light" | undefined,
+): NodeJS.ProcessEnv {
+  return {
+    ...env,
+    [HANDOFF_ENV]: "1",
+    ...(themeMode ? { [HANDOFF_THEME_MODE_ENV]: themeMode } : {}),
+  };
+}
+
+/** Narrow an IPC payload to one bounded handoff protocol message. */
+export function parseTerminalHandoffMessage(value: unknown): TerminalHandoffMessage | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const message = value as Record<string, unknown>;
+  if (message.protocol !== PROTOCOL) return undefined;
+  if (message.kind === "ready" || message.kind === "release") {
+    return { protocol: PROTOCOL, kind: message.kind };
+  }
+  if (message.kind === "failed" && typeof message.message === "string") {
+    return { protocol: PROTOCOL, kind: "failed", message: message.message.slice(0, 2_000) };
+  }
+  return undefined;
+}
+
+/** Build one authenticated-by-inheritance IPC message for the handoff peer. */
+export function terminalHandoffMessage(kind: "ready" | "release"): TerminalHandoffMessage {
+  return { protocol: PROTOCOL, kind };
+}
+
+/** Tell the parent startup succeeded, then wait boundedly for exclusive terminal ownership. */
+export async function awaitTerminalHandoffRelease({
+  env = process.env,
+  timeoutMs = 10_000,
+}: {
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+} = {}) {
+  if (!hasTerminalHandoff(env)) return;
+  if (typeof process.send !== "function" || !process.connected) {
+    throw new Error("The terminal handoff channel is unavailable.");
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      process.off("message", onMessage);
+      process.off("disconnect", onDisconnect);
+      if (error) reject(error);
+      else resolve();
+    };
+    const onMessage = (value: unknown) => {
+      const message = parseTerminalHandoffMessage(value);
+      if (message?.kind === "release") finish();
+    };
+    const onDisconnect = () => finish(new Error("The terminal handoff parent disconnected."));
+    const timeout = setTimeout(
+      () => finish(new Error("Timed out waiting for terminal ownership.")),
+      timeoutMs,
+    );
+    timeout.unref?.();
+    process.on("message", onMessage);
+    process.once("disconnect", onDisconnect);
+    process.send!(terminalHandoffMessage("ready"), (error) => {
+      if (error) finish(error);
+    });
+  });
+  process.disconnect?.();
+  delete env[HANDOFF_ENV];
+  delete env[HANDOFF_THEME_MODE_ENV];
+}
+
+/** Report a bounded pre-render startup failure to a waiting parent. */
+export async function reportTerminalHandoffFailure(
+  error: unknown,
+  env: NodeJS.ProcessEnv = process.env,
+) {
+  if (!hasTerminalHandoff(env) || typeof process.send !== "function" || !process.connected) {
+    return false;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  await new Promise<void>((resolve) => {
+    process.send!({ protocol: PROTOCOL, kind: "failed", message: message.slice(0, 2_000) }, () =>
+      resolve(),
+    );
+  });
+  process.disconnect?.();
+  return true;
+}

src/main.tsx

@@ -7,6 +7,10 @@ import { prepareStartupPlan } from "./app/startup";
 import { sanitizeTerminalText } from "./lib/terminalText";
 import { serveSessionBrokerDaemon } from "./session/broker/brokerServer";
 import { runSessionCommand } from "./session/agent/commands";
+import {
+  awaitTerminalHandoffRelease,
+  reportTerminalHandoffFailure,
+} from "./core/process/terminalHandoff";
 
 async function main() {
   const startupPlan = await prepareStartupPlan();
@@ -128,11 +132,18 @@ async function main() {
   }
 
   // OpenTUI stays behind the interactive plan so headless commands never materialize its embedded
-  // native library. The highlighting client starts the compiled worker only when an opted-in,
-  // eligible diff needs it, so normal sessions do not pay its startup cost. The interactive
-  // app owns that worker's disposal: this call returns once the app is mounted, not once it exits.
+  // native library. Load it before declaring a delegated review ready so terminal release is
+  // followed immediately by renderer creation rather than another module-loading gap.
+  const { runInteractiveApp } = await import("./ui/runInteractiveApp");
+
+  // A history parent keeps its loading frame mounted until review bootstrap and renderer code are
+  // ready. Wait for exclusive terminal ownership before mounting the child renderer.
+  await awaitTerminalHandoffRelease();
+
+  // The highlighting client starts the compiled worker only when an opted-in, eligible diff needs
+  // it, so normal sessions do not pay its startup cost. The interactive app owns that worker's
+  // disposal: this call returns once the app is mounted, not once it exits.
   try {
-    const { runInteractiveApp } = await import("./ui/runInteractiveApp");
     await runInteractiveApp(startupPlan);
   } catch (error) {
     startupPlan.controllingTerminal?.close();
@@ -143,7 +154,7 @@ async function main() {
   }
 }
 
-await main().catch((error) => {
-  process.stderr.write(formatCliError(error));
-  process.exit(1);
+await main().catch(async (error) => {
+  if (!(await reportTerminalHandoffFailure(error))) process.stderr.write(formatCliError(error));
+  process.exitCode = 1;
 });