@cueloop/client 0.1.0-alpha.74 → 0.1.0-alpha.76

package/src/diff-intraline.ts

@@ -83,12 +83,30 @@ export function intralineRunsByRow(rows: DiffRow[]): Map<number, IntralineRun[]>
 /** Lines this similar (word-set overlap) are treated as the same line edited. */
 const SIMILAR_MIN_WORD_OVERLAP = 0.3;
 
+/** Lower-cased word set of a line for the similarity gate, cached per distinct line within a block so
+ *  the LCS grid tokenizes each line once instead of once per comparison. */
+function lineWordSetCache(): (text: string) => ReadonlySet<string> {
+  const cache = new Map<string, ReadonlySet<string>>();
+
+  return (text) => {
+    const cached = cache.get(text);
+    if (cached !== undefined) return cached;
+    const words = new Set(text.toLowerCase().split(/\s+/).filter(Boolean));
+    cache.set(text, words);
+
+    return words;
+  };
+}
+
 /** Whether two lines are the same line edited, by case-insensitive word-set
  *  overlap - the matching gate, distinct from the case-sensitive word diff. */
-function linesSimilar(oldText: string, newText: string): boolean {
-  const words = (text: string) => new Set(text.toLowerCase().split(/\s+/).filter(Boolean));
-  const oldWords = words(oldText);
-  const newWords = words(newText);
+function linesSimilar(
+  wordsOf: (text: string) => ReadonlySet<string>,
+  oldText: string,
+  newText: string,
+): boolean {
+  const oldWords = wordsOf(oldText);
+  const newWords = wordsOf(newText);
 
   if (oldWords.size === 0 && newWords.size === 0) return true;
   let intersection = 0;
@@ -112,8 +130,11 @@ function alignedPairs(deletionTexts: string[], additionTexts: string[]): Array<[
   const pairs: Array<[number, number]> = [];
   let deletionOffset = 0;
   let additionOffset = 0;
+  const wordsOf = lineWordSetCache();
 
-  for (const op of lcsDiff(deletionTexts, additionTexts, linesSimilar)) {
+  for (const op of lcsDiff(deletionTexts, additionTexts, (deletionText, additionText) =>
+    linesSimilar(wordsOf, deletionText, additionText),
+  )) {
     if (op.kind === "ctx") {
       pairs.push([deletionOffset, additionOffset]);
       deletionOffset++;

package/src/perf/otlp-trace.test.ts

@@ -0,0 +1,116 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+  buildOtlpTracePayload,
+  phaseMarksToSpans,
+  postOtlpTrace,
+  type TraceSpan,
+} from "./otlp-trace";
+
+afterEach(() => {
+  delete process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+});
+
+const span: TraceSpan = {
+  traceId: "0123456789abcdef0123456789abcdef",
+  spanId: "0123456789abcdef",
+  name: "cueloop.interaction",
+  startTimeUnixNano: "1000",
+  endTimeUnixNano: "2000",
+  attributes: [
+    { key: "terminal.trigger", value: { stringValue: "key:j" } },
+    { key: "terminal.frame.budget_ms", value: { doubleValue: 16.7 } },
+    { key: "terminal.backpressure", value: { boolValue: true } },
+  ],
+};
+
+test("buildOtlpTracePayload carries service.name and maps scalar attributes to OTLP values", () => {
+  const payload = buildOtlpTracePayload("cueloop-client", [span]);
+
+  expect(payload).toEqual({
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [{ key: "service.name", value: { stringValue: "cueloop-client" } }],
+        },
+        scopeSpans: [
+          {
+            spans: [
+              {
+                traceId: "0123456789abcdef0123456789abcdef",
+                spanId: "0123456789abcdef",
+                parentSpanId: "",
+                name: "cueloop.interaction",
+                startTimeUnixNano: "1000",
+                endTimeUnixNano: "2000",
+                attributes: [
+                  { key: "terminal.trigger", value: { stringValue: "key:j" } },
+                  { key: "terminal.frame.budget_ms", value: { doubleValue: 16.7 } },
+                  { key: "terminal.backpressure", value: { boolValue: true } },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  });
+});
+
+test("phaseMarksToSpans builds a scope root with one child span per phase under one trace", () => {
+  const spans = phaseMarksToSpans("startup", [
+    { label: "renderer", elapsedMs: 10 },
+    { label: "firstFrame", elapsedMs: 20 },
+  ]);
+
+  expect(spans).toHaveLength(3);
+  const [root, first, second] = spans;
+  expect(root!.name).toBe("cueloop.startup");
+  expect(root!.parentSpanId).toBeUndefined();
+  expect(first!.name).toBe("cueloop.startup.renderer");
+  expect(first!.parentSpanId).toBe(root!.spanId);
+  expect(second!.parentSpanId).toBe(root!.spanId);
+  expect(new Set(spans.map((each) => each.traceId)).size).toBe(1);
+});
+
+test("postOtlpTrace sends no request when the endpoint is unset", async () => {
+  const requests: string[] = [];
+  const server = Bun.serve({
+    port: 0,
+    fetch(request) {
+      requests.push(request.url);
+
+      return new Response("{}");
+    },
+  });
+  try {
+    await postOtlpTrace("cueloop-client", [span]);
+  } finally {
+    await server.stop(true);
+  }
+
+  expect(requests).toHaveLength(0);
+});
+
+test("postOtlpTrace POSTs OTLP JSON to /v1/traces when the endpoint is set", async () => {
+  const requests: string[] = [];
+  const server = Bun.serve({
+    port: 0,
+    async fetch(request) {
+      requests.push(`${request.method} ${new URL(request.url).pathname}\n${await request.text()}`);
+
+      return new Response("{}");
+    },
+  });
+  // a trailing slash must not double up into "//v1/traces"
+  process.env.OTEL_EXPORTER_OTLP_ENDPOINT = `http://127.0.0.1:${server.port}/`;
+  try {
+    await postOtlpTrace("cueloop-client", [span]);
+  } finally {
+    await server.stop(true);
+  }
+
+  expect(requests).toHaveLength(1);
+  expect(requests[0]).toContain("POST /v1/traces");
+  expect(requests[0]).toContain('"service.name"');
+  expect(requests[0]).toContain("cueloop.interaction");
+});

package/src/perf/otlp-trace.ts

@@ -0,0 +1,130 @@
+/**
+ * Ship perf spans to a local OTLP/HTTP trace viewer (kundi) so an interaction's phases read as a
+ * callstack. Every export is a no-op unless OTEL_EXPORTER_OTLP_ENDPOINT is set. Tracing never throws
+ * into the app: a failed POST is swallowed. Attributes are scalar-only, matching the viewer's decoder.
+ */
+
+import type { PhaseMark } from "./perf-timings";
+
+export type SpanAttributeValue =
+  | { stringValue: string }
+  | { doubleValue: number }
+  | { boolValue: boolean };
+
+export interface SpanAttribute {
+  key: string;
+  value: SpanAttributeValue;
+}
+
+export interface TraceSpan {
+  traceId: string;
+  spanId: string;
+  parentSpanId?: string;
+  name: string;
+  startTimeUnixNano: string;
+  endTimeUnixNano: string;
+  attributes?: readonly SpanAttribute[];
+}
+
+function randomHex(bytes: number): string {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+
+  return Array.from(buffer, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+/** A 16-byte trace id as 32 lowercase hex chars, per the OTLP wire format. */
+export function newTraceId(): string {
+  return randomHex(16);
+}
+
+/** An 8-byte span id as 16 lowercase hex chars, per the OTLP wire format. */
+export function newSpanId(): string {
+  return randomHex(8);
+}
+
+/** Build the OTLP/JSON `resourceSpans` body the trace viewer's `/v1/traces` decoder reads. */
+export function buildOtlpTracePayload(serviceName: string, spans: readonly TraceSpan[]) {
+  return {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [{ key: "service.name", value: { stringValue: serviceName } }],
+        },
+        scopeSpans: [
+          {
+            spans: spans.map((span) => ({
+              traceId: span.traceId,
+              spanId: span.spanId,
+              // the viewer reads a missing parent as root; an empty string is the same, without a conditional key
+              parentSpanId: span.parentSpanId ?? "",
+              name: span.name,
+              startTimeUnixNano: span.startTimeUnixNano,
+              endTimeUnixNano: span.endTimeUnixNano,
+              attributes: (span.attributes ?? []).map((attribute) => ({
+                key: attribute.key,
+                value: attribute.value,
+              })),
+            })),
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function nanosFromPerfMs(milliseconds: number): string {
+  const originNs = BigInt(Math.round(performance.timeOrigin * 1e6));
+
+  return String(originNs + BigInt(Math.round(milliseconds * 1e6)));
+}
+
+/** Turn drained phase marks into a span tree: a `scope` root with one child span per phase, in order. */
+export function phaseMarksToSpans(scope: string, marks: readonly PhaseMark[]): TraceSpan[] {
+  const totalMs = marks.reduce((sum, mark) => sum + mark.elapsedMs, 0);
+  const endMs = performance.now();
+  const startMs = endMs - totalMs;
+  const traceId = newTraceId();
+  const rootSpanId = newSpanId();
+  const root: TraceSpan = {
+    traceId,
+    spanId: rootSpanId,
+    name: `cueloop.${scope}`,
+    startTimeUnixNano: nanosFromPerfMs(startMs),
+    endTimeUnixNano: nanosFromPerfMs(endMs),
+  };
+
+  let cursorMs = startMs;
+  const children = marks.map((mark) => {
+    const phaseStartMs = cursorMs;
+    cursorMs += mark.elapsedMs;
+
+    return {
+      traceId,
+      spanId: newSpanId(),
+      parentSpanId: rootSpanId,
+      name: `cueloop.${scope}.${mark.label}`,
+      startTimeUnixNano: nanosFromPerfMs(phaseStartMs),
+      endTimeUnixNano: nanosFromPerfMs(cursorMs),
+    };
+  });
+
+  return [root, ...children];
+}
+
+/** POST the spans to `${OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces` as OTLP/JSON; a no-op when the endpoint is unset. */
+export async function postOtlpTrace(
+  serviceName: string,
+  spans: readonly TraceSpan[],
+): Promise<void> {
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (endpoint === undefined || spans.length === 0) return;
+
+  // strip a trailing slash so an endpoint like "http://host:4318/" does not become "//v1/traces"
+  const base = endpoint.replace(/\/+$/, "");
+  await fetch(`${base}/v1/traces`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(buildOtlpTracePayload(serviceName, spans)),
+  }).catch(() => undefined);
+}

package/src/perf/perf-report.ts

@@ -0,0 +1,17 @@
+/**
+ * Report the drained perf marks for a scope two ways from one set of instrumentation: a phase block on
+ * stderr when CUELOOP_PERF=1, and a kundi span tree when the OTLP endpoint is set. No-op when neither is on.
+ */
+
+import { formatPerfBlock, takePerfMarks } from "./perf-timings";
+import { phaseMarksToSpans, postOtlpTrace } from "./otlp-trace";
+
+const PERF_SERVICE_NAME = "cueloop-client";
+
+export function reportPerfMarks(scope: string): void {
+  const marks = takePerfMarks();
+  if (marks.length === 0) return;
+
+  if (process.env.CUELOOP_PERF === "1") process.stderr.write(formatPerfBlock(scope, marks));
+  void postOtlpTrace(PERF_SERVICE_NAME, phaseMarksToSpans(scope, marks));
+}

package/src/perf/perf-timings.test.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test";
+import { formatPerfBlock } from "./perf-timings";
+
+test("formatPerfBlock renders labeled rows and a summed TOTAL", () => {
+  const block = formatPerfBlock("startup", [
+    { label: "connect", elapsedMs: 12.34 },
+    { label: "firstRender", elapsedMs: 7.66 },
+  ]);
+
+  expect(block).toContain("--- perf startup ---");
+  expect(block).toContain("connect  12.3ms");
+  expect(block).toContain("firstRender  7.7ms");
+  expect(block).toContain("TOTAL  20.0ms");
+});
+
+test("formatPerfBlock totals to zero for no marks", () => {
+  expect(formatPerfBlock("startup", [])).toContain("TOTAL  0.0ms");
+});

package/src/perf/perf-timings.ts

@@ -0,0 +1,38 @@
+/** Startup phase timing for the perf harness: records elapsed ms between marks and flushes a
+ * labeled block to stderr. Every entry point is a no-op unless the CUELOOP_PERF env var is "1". */
+
+export interface PhaseMark {
+  label: string;
+  elapsedMs: number;
+}
+
+const phaseMarks: PhaseMark[] = [];
+let lastMarkAt: number | null = null;
+
+/** Marks record when the stderr timer (CUELOOP_PERF=1) or the kundi exporter (OTEL endpoint) is on. */
+function perfInstrumentationEnabled(): boolean {
+  return process.env.CUELOOP_PERF === "1" || process.env.OTEL_EXPORTER_OTLP_ENDPOINT !== undefined;
+}
+
+/** Record the elapsed ms since the previous mark (or process start) under `label`. */
+export function perfMark(label: string): void {
+  if (!perfInstrumentationEnabled()) return;
+  const now = performance.now();
+  phaseMarks.push({ label, elapsedMs: now - (lastMarkAt ?? 0) });
+  lastMarkAt = now;
+}
+
+/** Drain the recorded marks for a reporter to format or export; empties the buffer for the next scope. */
+export function takePerfMarks(): PhaseMark[] {
+  lastMarkAt = null;
+
+  return phaseMarks.splice(0, phaseMarks.length);
+}
+
+/** Render phase deltas as the stderr block: a header, one indented row per mark, a summed TOTAL. */
+export function formatPerfBlock(scope: string, marks: readonly PhaseMark[]): string {
+  const totalMs = marks.reduce((sum, mark) => sum + mark.elapsedMs, 0);
+  const rows = marks.map((mark) => `  ${mark.label}  ${mark.elapsedMs.toFixed(1)}ms`);
+
+  return [`--- perf ${scope} ---`, ...rows, `  TOTAL  ${totalMs.toFixed(1)}ms`, ""].join("\n");
+}

package/src/run.ts

@@ -5,6 +5,8 @@ import { createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 import { App } from "./App";
 import { loadConfig } from "./config";
+import { perfMark } from "./perf/perf-timings";
+import { reportPerfMarks } from "./perf/perf-report";
 import { defaultLayout, type LaunchLayout } from "./launch-layout";
 
 export interface RunClientOptions {
@@ -14,8 +16,9 @@ export interface RunClientOptions {
   layout?: LaunchLayout;
 }
 
-/** OSC background query budget: brief so a terminal that never answers falls back to dark. */
-const THEME_QUERY_TIMEOUT_MS = 200;
+/** OSC background query budget: long enough for a terminal to answer, short enough that one that never
+ *  does not stall the launch; a non-answering terminal falls back to dark after this. */
+const THEME_QUERY_TIMEOUT_MS = 100;
 
 export async function runClient(options: RunClientOptions): Promise<number> {
   // mouse movement reporting makes multiplexers forward drags to the app,
@@ -26,8 +29,20 @@ export async function runClient(options: RunClientOptions): Promise<number> {
     options.layout ??
     (options.sessionId === undefined ? (loadConfig().ui.layout ?? defaultLayout()) : undefined);
   const renderer = await createCliRenderer({ enableMouseMovement: true });
+  // a full screen of measured elements each holds a frame listener; lift the default-10 ceiling so a
+  // busy view does not trip a false leak warning, while a runaway subscription still would
+  renderer.setMaxListeners(64);
+  perfMark("renderer");
+  // re-assert mouse reporting on focus-in: a multiplexer can drop it, stranding the pointer in native selection
+  renderer.on("focus", () => {
+    renderer.useMouse = false;
+    renderer.useMouse = true;
+  });
+  // block first paint on the theme query only briefly, so an answering terminal paints its real theme
+  // with no flash while a non-answering one falls back to dark within the budget
   const appearance =
     (await renderer.waitForThemeMode(THEME_QUERY_TIMEOUT_MS).catch(() => null)) ?? "dark";
+  perfMark("themeQuery");
 
   return new Promise<number>((resolve) => {
     let exited = false;
@@ -53,7 +68,12 @@ export async function runClient(options: RunClientOptions): Promise<number> {
         appearance,
         layout,
         onExit: shutdown,
+        onReady: () => {
+          perfMark("firstFrame");
+          reportPerfMarks("startup");
+        },
       }),
     );
+    perfMark("render");
   });
 }

package/src/thread-chords.test.ts

@@ -1,8 +1,40 @@
 import { describe, expect, test } from "bun:test";
-import { resolveThreadChord } from "./thread-chords";
+import {
+  DEFAULT_LEADER,
+  leaderHint,
+  matchesLeader,
+  resolveLeaderCommand,
+  resolveThreadChord,
+} from "./thread-chords";
 
 const owner = { composing: false, isOwner: true, resolved: false, treeActive: false };
 
+describe("the command leader", () => {
+  test("matchesLeader recognizes the configured chord and nothing else", () => {
+    expect(matchesLeader({ ctrl: true, name: "g" }, [DEFAULT_LEADER])).toBe(true);
+    expect(matchesLeader({ ctrl: true, name: "G" }, [DEFAULT_LEADER])).toBe(true);
+    expect(matchesLeader({ name: "g" }, [DEFAULT_LEADER])).toBe(false);
+    expect(matchesLeader({ ctrl: true, name: "x" }, [DEFAULT_LEADER])).toBe(false);
+    expect(matchesLeader({ ctrl: true, meta: true, name: "g" }, [DEFAULT_LEADER])).toBe(false);
+    expect(matchesLeader({ name: "," }, [","])).toBe(true);
+  });
+
+  test("leaderHint renders the glyph plus a trailing space", () => {
+    expect(leaderHint(["ctrl+g"])).toBe("⌃g ");
+    expect(leaderHint([","])).toBe(", ");
+  });
+
+  test("a key after the leader runs the same intent as its Option chord", () => {
+    const diff = { ...owner, isDiff: true };
+
+    expect(resolveLeaderCommand({ name: "x" }, diff)).toEqual({ type: "rejectChange" });
+    expect(resolveLeaderCommand({ name: "X" }, diff)).toEqual({ type: "rejectHunk" });
+    expect(resolveLeaderCommand({ name: "x" }, owner)).toEqual({ type: "cut" });
+    expect(resolveLeaderCommand({ name: "return" }, owner)).toEqual({ type: "openSubmit" });
+    expect(resolveLeaderCommand({ name: "x" }, { ...owner, composing: true })).toBeNull();
+  });
+});
+
 describe("resolveThreadChord", () => {
   test("ctrl+enter opens the submit overlay for an owner with an open review", () => {
     // Assert: the terminal-safe chord and the cmd forms all submit

package/src/thread-chords.ts

@@ -28,16 +28,70 @@ export interface ThreadChordContext {
   isDiff?: boolean;
 }
 
-/** The diff-review chords: option plus a letter, acting on the caret's row or file. */
-export const DIFF_CHORD_ENTRIES = [
-  { keys: "⌥x / ⌥X", label: "reject the change / the hunk" },
-  { keys: "⌥u", label: "restore the last rejection" },
-  { keys: "⌥c", label: "collapse the file to its band" },
-  { keys: "⌥d", label: "split / stacked (when wide)" },
-  { keys: "⌥k", label: "start the guided walk" },
-] as const;
+export const DEFAULT_LEADER = "ctrl+g";
+
+export function leaderCombosFor(configured: readonly string[] | undefined): readonly string[] {
+  return configured ?? [DEFAULT_LEADER];
+}
+
+const MOD_GLYPHS = new Map<string, string>([
+  ["ctrl", "⌃"],
+  ["control", "⌃"],
+  ["meta", "⌥"],
+  ["alt", "⌥"],
+  ["option", "⌥"],
+  ["shift", "⇧"],
+  ["cmd", "⌘"],
+  ["super", "⌘"],
+]);
+
+function comboParts(combo: string) {
+  const parts = combo.split("+");
+
+  return { mods: parts.slice(0, -1).map((part) => part.toLowerCase()), name: parts.at(-1) ?? "" };
+}
 
-/** The cheatsheet rows for the chords, in the same order they are resolved. */
+export function leaderHint(combos: readonly string[]): string {
+  const { mods, name } = comboParts(combos[0] ?? DEFAULT_LEADER);
+
+  return `${mods.map((mod) => MOD_GLYPHS.get(mod) ?? mod).join("")}${name} `;
+}
+
+export function matchesLeader(
+  key: { ctrl?: boolean; meta?: boolean; shift?: boolean; super?: boolean; name: string },
+  combos: readonly string[],
+): boolean {
+  return combos.some((combo) => {
+    const { mods, name } = comboParts(combo);
+
+    return (
+      key.name.toLowerCase() === name.toLowerCase() &&
+      Boolean(key.ctrl) === (mods.includes("ctrl") || mods.includes("control")) &&
+      Boolean(key.shift) === mods.includes("shift") &&
+      Boolean(key.super) === (mods.includes("cmd") || mods.includes("super")) &&
+      Boolean(key.meta) ===
+        (mods.includes("meta") || mods.includes("alt") || mods.includes("option"))
+    );
+  });
+}
+
+export interface ChordEntry {
+  keys: string;
+  label: string;
+}
+
+/** The diff-review chords: the leader (or Option) plus a letter, on the caret's row or file. */
+export function diffChordEntries(hint: string): ChordEntry[] {
+  return [
+    { keys: `${hint}x / ${hint}X`, label: "reject the change / the hunk" },
+    { keys: `${hint}u`, label: "restore the last rejection" },
+    { keys: `${hint}c`, label: "collapse the file to its band" },
+    { keys: `${hint}d`, label: "split / stacked (when wide)" },
+    { keys: `${hint}k`, label: "start the guided walk" },
+  ];
+}
+
+/** The session chords stay on Ctrl, which terminals deliver reliably. */
 export const THREAD_CHORD_ENTRIES = [
   { keys: "⌃enter", label: "submit the review" },
   { keys: "⌃e", label: "edit in $EDITOR" },
@@ -45,27 +99,31 @@ export const THREAD_CHORD_ENTRIES = [
   { keys: "⌃r", label: "cycle the rail" },
 ] as const;
 
-/** The rail and curation chords: option (alt) plus the plan sheet's old letter. */
-export const RAIL_CHORD_ENTRIES = [
-  { keys: "⌥n / ⌥p", label: "next / previous card" },
-  { keys: "⌥e", label: "edit the card" },
-  { keys: "⌥⌫", label: "delete the card" },
-  { keys: "⌥r", label: "rename the author" },
-  { keys: "⌥x", label: "cut the block" },
-  { keys: "⌥u", label: "restore the last cut" },
-  { keys: "⌥w / ⌥s", label: "widen / narrow the rail" },
-] as const;
+/** The rail and curation chords: the leader plus the plan sheet's old letter. */
+export function railChordEntries(hint: string): ChordEntry[] {
+  return [
+    { keys: `${hint}n / ${hint}p`, label: "next / previous card" },
+    { keys: `${hint}e`, label: "edit the card" },
+    { keys: `${hint}⌫`, label: "delete the card" },
+    { keys: `${hint}r`, label: "rename the author" },
+    { keys: `${hint}x`, label: "cut the block" },
+    { keys: `${hint}u`, label: "restore the last cut" },
+    { keys: "⌥w / ⌥s", label: "widen / narrow the rail" },
+  ];
+}
 
-/** The tree chords: option plus a letter, all on the rail's Tree tab. */
-export const TREE_CHORD_ENTRIES = [
-  { keys: "⌥t", label: "show / hide the tree" },
-  { keys: "⌥n / ⌥p", label: "next / previous entry" },
-  { keys: "⌥g", label: "go to the entry" },
-  { keys: "⌥b", label: "branch off the tip" },
-  { keys: "⌥l", label: "label a checkpoint" },
-  { keys: "⌥f", label: "fork the path" },
-  { keys: "⌥h", label: "fork and hand off" },
-] as const;
+/** The tree chords: the leader plus a letter, all on the rail's Tree tab. */
+export function treeChordEntries(hint: string): ChordEntry[] {
+  return [
+    { keys: `${hint}t`, label: "show / hide the tree" },
+    { keys: `${hint}n / ${hint}p`, label: "next / previous entry" },
+    { keys: `${hint}g`, label: "go to the entry" },
+    { keys: `${hint}b`, label: "branch off the tip" },
+    { keys: `${hint}l`, label: "label a checkpoint" },
+    { keys: `${hint}f`, label: "fork the path" },
+    { keys: `${hint}h`, label: "fork and hand off" },
+  ];
+}
 
 export function resolveThreadChord(
   key: ThreadChordKey,
@@ -89,6 +147,33 @@ export function resolveThreadChord(
   return null;
 }
 
+export function resolveLeaderCommand(
+  key: ThreadChordKey,
+  context: ThreadChordContext,
+): Intent | null {
+  if (context.composing) return null;
+  if (key.name === "return" || key.name === "enter") {
+    if (!context.isOwner) return READ_ONLY;
+
+    return context.resolved ? null : { type: "openSubmit" };
+  }
+
+  return (
+    (context.isDiff && resolveDiffChord(key.name, context)) || resolveRailChord(key.name, context)
+  );
+}
+
+export function dispatchLeaderCommand(
+  key: { name: string; shift?: boolean },
+  context: ThreadChordContext,
+  dispatch: (intent: Intent) => void,
+): void {
+  const name = key.shift ? key.name.toUpperCase() : key.name;
+  const chord = resolveLeaderCommand({ name }, context);
+
+  if (chord) dispatch(chord);
+}
+
 /** The diff's row and file chords; null lets the rail chords answer the letter. */
 function resolveDiffChord(name: string, context: ThreadChordContext): Intent | null {
   switch (name) {

package/src/thread-controller.ts

@@ -648,9 +648,10 @@ class Controller implements ReviewController {
     // eager: capture the live working-tree diff so the Changes navigator and its file tabs render a real diff
     if (this.client?.repoDiff !== undefined) {
       const diff = await this.client.repoDiff(this.sidebarRepoRoot());
-      // a thread switch during the request would let this response overwrite the new
-      // thread's diff, showing changes from the wrong repo; drop it when the session moved on
-      if (this.snapshot.session !== session) return diff.files;
+      // a thread switch during the request would let this response overwrite the new thread's diff,
+      // showing changes from the wrong repo; compare the thread id, not the object, so an unrelated
+      // re-render that replaced the snapshot for the SAME thread does not drop its diff to "No changes"
+      if (this.snapshot.session?.id !== session?.id) return diff.files;
       this.liveDiff = diff;
       // rows() derive from the fresh patch; re-render so an open diff tab repaints
       this.update({});