@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.101

package/src/app/App.workbench.test.tsx

@@ -0,0 +1,1149 @@
+/** The four-pane workbench in the virtual terminal, mirroring the browser prototype's interactions:
+ * a diff session lays out Threads | Thread | Changes editor | Project sidebar; the diff (±) and tree
+ * toggles are mutually exclusive and switching to tree keeps the Changes editor open; a project-tree
+ * file opens as a read-only contents tab; the split control offers four directions and the arrow keys
+ * split; dismissing the Changes tab collapses the Changes pane but keeps the Project sidebar;
+ * the right-sidebar toggle collapses the region to a thin rail and reopens it; zoom hides the Thread pane
+ * while the sidebars stay. */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import React from "react";
+import { testRender as renderTestComponent } from "@opentui/react/test-utils";
+import { DaemonServer } from "@cueloop/daemon";
+import type { Thread } from "@cueloop/schema";
+import { App } from "./App";
+import { loadConfig } from "../settings/config";
+import { pairLayout, planLayout, reviewLayout } from "./launch-layout";
+import {
+  dragText,
+  isolateUserConfig,
+  locateText,
+  press,
+  pressKey,
+  typeText,
+  waitForState,
+  waitForText,
+  waitForTextGone,
+  renderReadyApp as renderReadyTestApp,
+} from "../testing/test-support";
+import { NERD } from "../ui/components/primitives/icons";
+
+const PATCH = `diff --git a/src/store.ts b/src/store.ts
+index 111..222 100644
+--- a/src/store.ts
++++ b/src/store.ts
+@@ -1,3 +1,3 @@
+ export class Store {
+-  private items = [];
++  private items = new Map();
+ }
+`;
+
+let home: string;
+let repo: string;
+let restoreUserConfig: () => void;
+let server: DaemonServer;
+let session: Thread;
+const renderers = new Set<Awaited<ReturnType<typeof renderTestComponent>>["renderer"]>();
+
+async function testRender(...args: Parameters<typeof renderTestComponent>) {
+  const setup = await renderTestComponent(...args);
+
+  renderers.add(setup.renderer);
+
+  return setup;
+}
+
+async function renderReadyApp(...args: Parameters<typeof renderReadyTestApp>) {
+  const setup = await renderReadyTestApp(...args);
+
+  renderers.add(setup.renderer);
+
+  return setup;
+}
+
+/** A throwaway git repo so the Project tree (git ls-files) and file contents resolve without a real checkout. */
+function makeRepo(): string {
+  const root = mkdtempSync(join(tmpdir(), "cueloop-workbench-repo-"));
+
+  mkdirSync(join(root, "src"), { recursive: true });
+  writeFileSync(join(root, "README.md"), "# Workbench Fixture\n\nA tiny tracked repo.\n");
+  writeFileSync(join(root, "src", "store.ts"), "export class Store {}\n");
+  writeFileSync(join(root, "src", "util.ts"), "export const noop = () => {};\n");
+  const git = (args: string[]) => Bun.spawnSync(["git", "-C", root, ...args]);
+
+  git(["init", "-q"]);
+  git(["config", "user.email", "fixture@example.com"]);
+  git(["config", "user.name", "Fixture"]);
+  git(["add", "-A"]);
+  git(["commit", "-q", "-m", "seed"]);
+
+  return root;
+}
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-workbench-"));
+  repo = makeRepo();
+  restoreUserConfig = isolateUserConfig(home);
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  session = server.core.sessionCreate({
+    workspace: { repoRoot: repo, branch: "main" },
+    artifact: { type: "diff", content: PATCH, meta: { title: "working tree" } },
+  });
+});
+afterEach(() => {
+  for (const renderer of renderers) {
+    if (!renderer.isDestroyed) renderer.destroy();
+  }
+  renderers.clear();
+  restoreUserConfig();
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+  rmSync(repo, { recursive: true, force: true });
+});
+
+async function renderApp() {
+  const setup = await renderReadyApp(<App home={home} sessionId={session.id} />, {
+    width: 160,
+    height: 20,
+  });
+
+  await waitForText(setup, "store.ts");
+
+  return setup;
+}
+
+type Setup = Awaited<ReturnType<typeof renderApp>>;
+
+/** The header controls sit on the top content row of the compact header. */
+const HEADER_ROW = 0;
+const BARE_NAV_HINT = "c comment · z fold · type to leave";
+
+/** Column of a Project-header toggle, located by its own glyph so spacing changes never break the click. */
+function toggleColumn(setup: Setup, glyph: string): number {
+  return setup.captureCharFrame().split("\n")[HEADER_ROW]!.lastIndexOf(glyph);
+}
+const diffToggleColumn = (setup: Setup): number => toggleColumn(setup, "changes");
+const treeToggleColumn = (setup: Setup): number => toggleColumn(setup, "project");
+const rightToggleColumn = (setup: Setup): number => toggleColumn(setup, NERD.sidebarRight);
+// the collapsed rail shows the outline (off) variant, mirroring the left toggle's filled/outline states
+const railToggleColumn = (setup: Setup): number => toggleColumn(setup, NERD.sidebarRightOff);
+
+function changedFileVisibleInRightTree(frame: string, file: string): boolean {
+  return frame.split("\n").some((line) => {
+    const divider = line.lastIndexOf("│");
+
+    return divider >= 0 && line.slice(divider + 1).includes(file);
+  });
+}
+
+describe("the four-pane workbench", () => {
+  test("a bootstrapped workbench paints its changed-file list in the first usable frame", async () => {
+    const workbench = server.core.sessionCreate({
+      workspace: { repoRoot: repo, branch: "main" },
+      artifact: { type: "diff", content: "", meta: { title: "Workbench", workbench: true } },
+    });
+    const initialReview = {
+      session: workbench,
+      diff: {
+        patch: PATCH,
+        files: [
+          {
+            path: "src/store.ts",
+            oldContents: "export class Store { private items = []; }\n",
+            newContents: "export class Store { private items = new Map(); }\n",
+            status: "modified" as const,
+          },
+        ],
+      },
+    };
+    const setup = await renderReadyApp(
+      <App
+        home={home}
+        sessionId={workbench.id}
+        initialReview={initialReview}
+        layout={reviewLayout()}
+      />,
+      { width: 160, height: 20 },
+    );
+
+    expect(changedFileVisibleInRightTree(setup.captureCharFrame(), "store.ts")).toBe(true);
+    setup.renderer.destroy();
+  });
+
+  test("reopening Changes does not restore files from the launch snapshot", async () => {
+    const workbench = server.core.sessionCreate({
+      workspace: { repoRoot: repo, branch: "main" },
+      artifact: { type: "diff", content: "", meta: { title: "Workbench", workbench: true } },
+    });
+    const initialReview = {
+      session: workbench,
+      diff: {
+        patch: PATCH,
+        files: [
+          {
+            path: "src/store.ts",
+            oldContents: "before\n",
+            newContents: "after\n",
+            status: "modified" as const,
+          },
+        ],
+      },
+    };
+    const setup = await renderReadyApp(
+      <App
+        home={home}
+        sessionId={workbench.id}
+        initialReview={initialReview}
+        layout={reviewLayout()}
+      />,
+      { width: 160, height: 20 },
+    );
+
+    await waitForState(
+      setup,
+      () => !changedFileVisibleInRightTree(setup.captureCharFrame(), "store.ts"),
+    );
+    await setup.mockMouse.click(rightToggleColumn(setup), HEADER_ROW);
+    await waitForState(setup, () => diffToggleColumn(setup) === -1);
+    await setup.mockMouse.click(railToggleColumn(setup), HEADER_ROW);
+
+    expect(changedFileVisibleInRightTree(setup.captureCharFrame(), "store.ts")).toBe(false);
+    setup.renderer.destroy();
+  });
+
+  test("rapid wheel scrolling a large Changes diff keeps the app responsive", async () => {
+    const filePatches = Array.from({ length: 40 }, (_, fileIndex) => [
+      `diff --git a/file-${fileIndex}.ts b/file-${fileIndex}.ts`,
+      `--- a/file-${fileIndex}.ts`,
+      `+++ b/file-${fileIndex}.ts`,
+      "@@ -0,0 +1,10 @@",
+      ...Array.from(
+        { length: 10 },
+        (_, lineIndex) => `+line ${lineIndex} ${"dense source text ".repeat(40)}`,
+      ),
+    ]).flat();
+    const large = server.core.sessionCreate({
+      workspace: { repoRoot: repo, branch: "main" },
+      artifact: {
+        type: "diff",
+        content: [...filePatches, ""].join("\n"),
+        meta: { title: "large changes" },
+      },
+    });
+    const setup = await renderReadyApp(<App home={home} sessionId={large.id} />, {
+      width: 160,
+      height: 20,
+    });
+
+    await waitForText(setup, "file-0.ts");
+    for (const [index, direction] of Array.from({ length: 500 }, () => "down" as const).entries()) {
+      // eslint-disable-next-line no-await-in-loop
+      await setup.mockMouse.scroll(75, 10, direction);
+      if (index % 25 === 0) {
+        // eslint-disable-next-line no-await-in-loop
+        await setup.waitForVisualIdle();
+      }
+    }
+    await setup.waitForVisualIdle();
+    expect(setup.captureCharFrame()).toContain("changes");
+    setup.renderer.destroy();
+  }, 60000);
+
+  test("pair starts focused on the Project tree beside the zoomed Changes editor", async () => {
+    const setup = await renderReadyApp(
+      <App home={home} sessionId={session.id} layout={pairLayout()} />,
+      { width: 160, height: 20 },
+    );
+
+    await waitForText(setup, "README.md");
+    expect(setup.captureCharFrame()).toContain("Changes");
+    await pressKey(setup, "RETURN");
+    await waitForText(setup, "Workbench Fixture");
+    setup.renderer.destroy();
+  });
+
+  test("a live thread's Changes tree follows edits and a clean working tree", async () => {
+    const liveSession = server.core.sessionCreate({
+      workspace: { repoRoot: repo, branch: "main" },
+      artifact: { type: "diff", content: "", meta: { title: "live changes", workbench: true } },
+    });
+
+    writeFileSync(join(repo, "README.md"), "# Edited\n");
+    const setup = await renderReadyApp(
+      <App home={home} sessionId={liveSession.id} layout={reviewLayout()} />,
+      {
+        width: 160,
+        height: 20,
+      },
+    );
+
+    await waitForText(setup, "README.md");
+    writeFileSync(join(repo, "README.md"), "# Workbench Fixture\n\nA tiny tracked repo.\n");
+    await waitForState(setup, () => !setup.captureCharFrame().includes("README.md"));
+    writeFileSync(join(repo, "src", "util.ts"), "export const noop = () => 1;\n");
+    await waitForText(setup, "util.ts");
+  }, 12_000);
+
+  test("a frozen diff's Changes tree follows a new captured revision", async () => {
+    const frozen = server.core.sessionCreate({
+      workspace: { repoRoot: repo, branch: "main" },
+      artifact: {
+        type: "diff",
+        content: "diff --git a/README.md b/README.md\n",
+        files: [
+          {
+            path: "README.md",
+            status: "modified",
+            oldContents: "before\n",
+            newContents: "after\n",
+          },
+        ],
+        meta: { title: "captured diff" },
+      },
+    });
+    const setup = await renderReadyApp(
+      <App home={home} sessionId={frozen.id} layout={reviewLayout()} />,
+      { width: 160, height: 20 },
+    );
+
+    await waitForText(setup, "README.md");
+    server.core.sessionSubmitRevision(
+      frozen.id,
+      "diff --git a/src/util.ts b/src/util.ts\n",
+      [],
+      [
+        {
+          path: "src/util.ts",
+          status: "modified",
+          oldContents: "before\n",
+          newContents: "after\n",
+        },
+      ],
+    );
+    await waitForState(setup, () => {
+      const frame = setup.captureCharFrame();
+
+      return frame.includes("util.ts") && !frame.includes("README.md");
+    });
+    setup.renderer.destroy();
+  });
+
+  test("a diff session lays out the four panes with the diff toggle active", async () => {
+    const setup = await renderApp();
+
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("cueloop");
+    expect(frame).toContain("Changes");
+    expect(frame).toContain("store.ts");
+    expect(frame).toContain("src/store.ts");
+    expect(frame).toContain(NERD.copy);
+    // the diff (±) toggle exists in the Project header
+    expect(diffToggleColumn(setup)).toBeGreaterThan(0);
+  });
+
+  test("switching to the project tree keeps the Changes editor open", async () => {
+    const setup = await renderApp();
+
+    // the diff and tree toggles are mutually exclusive; switch to the full project tree
+    await setup.mockMouse.click(treeToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "README.md");
+
+    const frame = setup.captureCharFrame();
+
+    // the full tree is showing...
+    expect(frame).toContain("README.md");
+    expect(frame).toContain("src");
+    // ...and the Changes editor stayed open through the mode switch
+    expect(frame).toContain("Changes");
+  });
+
+  test("opening a project-tree file adds a read-only contents tab", async () => {
+    const setup = await renderApp();
+
+    await setup.mockMouse.click(treeToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "README.md");
+
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForText(setup, "Workbench Fixture");
+
+    const frame = setup.captureCharFrame();
+
+    // the contents tab carries the file's text with no diff markers
+    expect(frame).toContain("A tiny tracked repo.");
+    expect(frame.split("\n")[HEADER_ROW]!).toContain("README.md");
+  });
+
+  test("project clicks reuse one preview and a double-click keeps the file open once", async () => {
+    const setup = await renderApp();
+
+    await setup.mockMouse.click(treeToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "README.md");
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForState(setup, () =>
+      setup.captureCharFrame().split("\n")[HEADER_ROW]!.includes("README.md"),
+    );
+
+    const folder = locateText(setup, "src");
+
+    await setup.mockMouse.click(folder.column, folder.row);
+    await waitForText(setup, "util.ts");
+    const util = locateText(setup, "util.ts");
+
+    await setup.mockMouse.click(util.column, util.row);
+    await waitForState(setup, () => {
+      const header = setup.captureCharFrame().split("\n")[HEADER_ROW]!;
+
+      return header.includes("util.ts") && !header.includes("README.md");
+    });
+
+    await setup.mockMouse.doubleClick(util.column, util.row);
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForState(setup, () => {
+      const header = setup.captureCharFrame().split("\n")[HEADER_ROW]!;
+
+      return header.includes("util.ts") && header.includes("README.md");
+    });
+    await setup.mockMouse.click(util.column, util.row);
+    const header = setup.captureCharFrame().split("\n")[HEADER_ROW]!;
+
+    expect(header.match(/util\.ts/g)).toHaveLength(1);
+    expect(header.match(/README\.md/g)).toHaveLength(1);
+    setup.renderer.destroy();
+  });
+
+  test("the split control offers four directions and arrow-right makes two groups", async () => {
+    const setup = await renderApp();
+
+    await setup.mockMouse.click(treeToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "README.md");
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForText(setup, "Workbench Fixture");
+
+    // the split control appears only on a file tab
+    const split = locateText(setup, "split");
+
+    await setup.mockMouse.click(split.column, split.row);
+    await waitForText(setup, "right");
+
+    const menu = setup.captureCharFrame();
+
+    expect(menu).toContain("left");
+    expect(menu).toContain("right");
+    expect(menu).toContain("up");
+    expect(menu).toContain("down");
+
+    // the arrow keys drive the popover: right splits the group into two
+    await pressKey(setup, "ARROW_RIGHT");
+    await waitForState(setup, () =>
+      /│ Changes\s+│.*│ README\.md/.test(setup.captureCharFrame().split("\n")[HEADER_ROW]!),
+    );
+    expect(
+      setup
+        .captureCharFrame()
+        .split("\n")
+        [HEADER_ROW]!.match(/README\.md/g),
+    ).toHaveLength(1);
+  });
+
+  test("dismissing the Changes tab collapses the Changes pane but keeps the Project sidebar", async () => {
+    const setup = await renderApp();
+
+    const changes = locateText(setup, "Changes");
+
+    // the tab's close box sits just past the label; the ✕ is a hover affordance, the box always clicks
+    await setup.mockMouse.click(changes.column + 8, changes.row);
+    await waitForState(setup, () => !setup.captureCharFrame().includes("store.ts"));
+
+    const frame = setup.captureCharFrame();
+
+    // the Changes editor is gone...
+    expect(frame).not.toContain("store.ts");
+    // ...but the Project sidebar and its toggles remain
+    expect(diffToggleColumn(setup)).toBeGreaterThan(0);
+  });
+
+  test("the right-sidebar toggle closes the region and its header toggle reopens it", async () => {
+    const setup = await renderApp();
+
+    await setup.mockMouse.click(rightToggleColumn(setup), HEADER_ROW);
+    await waitForState(setup, () => !setup.captureCharFrame().includes("store.ts"));
+
+    // the right region is closed: no Changes editor, no Project tree toggles, no gutter
+    expect(setup.captureCharFrame()).not.toContain("store.ts");
+    expect(diffToggleColumn(setup)).toBe(-1);
+
+    // the reopen toggle (outline/off variant) rides the thread header; clicking it reopens the region
+    await setup.mockMouse.click(railToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "store.ts");
+    expect(diffToggleColumn(setup)).toBeGreaterThan(0);
+  });
+
+  test("the Threads toggle opens and closes the sidebar, relocating the brand", async () => {
+    const setup = await renderApp();
+
+    // deep-linked into a session, the Threads sidebar starts collapsed: the brand rides in the
+    // Thread header and the inbox groups are hidden
+    const collapsed = setup.captureCharFrame();
+
+    expect(collapsed).toContain("cueloop");
+    expect(collapsed).not.toContain("Threads");
+
+    // the sidebar toggle sits just left of the brand (one glyph plus its margin)
+    const brand = locateText(setup, "cueloop");
+
+    await setup.mockMouse.click(brand.column - 3, brand.row);
+    await waitForText(setup, "Threads");
+
+    // the Threads pane is open with its inbox groups, and the brand moved into its header
+    expect(setup.captureCharFrame()).toContain("Threads");
+
+    // toggling again collapses it back
+    const reopened = locateText(setup, "cueloop");
+
+    await setup.mockMouse.click(reopened.column - 3, reopened.row);
+    await waitForState(setup, () => !setup.captureCharFrame().includes("Threads"));
+    expect(setup.captureCharFrame()).not.toContain("Threads");
+  });
+
+  test("zoom hides the Thread pane while the sidebars stay", async () => {
+    const setup = await renderApp();
+
+    const zoom = locateText(setup, NERD.zoom);
+
+    await setup.mockMouse.click(zoom.column, zoom.row);
+    await waitForState(setup, () => !setup.captureCharFrame().includes("Select a thread"));
+
+    const frame = setup.captureCharFrame();
+
+    // the Thread pane's prompt is gone...
+    expect(frame).not.toContain("Select a thread");
+    // ...while the Changes editor and Project sidebar stay
+    expect(frame).toContain("store.ts");
+    expect(diffToggleColumn(setup)).toBeGreaterThan(0);
+  });
+
+  test("a create-command session remembers its zoom toggle for the next bare launch", async () => {
+    // a create-command opens the review zoomed; toggling zoom off must persist to the remembered layout
+    const setup = await renderReadyApp(
+      <App home={home} sessionId={session.id} layout={reviewLayout()} />,
+      {
+        width: 160,
+        height: 20,
+      },
+    );
+
+    await waitForText(setup, "store.ts");
+
+    const zoom = locateText(setup, NERD.zoom);
+
+    await setup.mockMouse.click(zoom.column, zoom.row);
+    await waitForState(
+      setup,
+      () =>
+        loadConfig({ userConfigPath: process.env.CUELOOP_CONFIG }).ui.layout?.zoomChanges === false,
+    );
+    expect(loadConfig({ userConfigPath: process.env.CUELOOP_CONFIG }).ui.layout?.zoomChanges).toBe(
+      false,
+    );
+  });
+
+  test("selecting a non-diff thread while zoomed exits zoom and restores the Thread pane", async () => {
+    // a second, non-diff thread to navigate to; its sync has no Changes editor to fill a zoom
+    server.core.sessionCreate({
+      workspace: { repoRoot: repo, branch: "main" },
+      artifact: {
+        type: "plan",
+        content: "# Zoomed Plan\n\nReview this plan.\n",
+        meta: { title: "Zoomed Plan" },
+      },
+    });
+    const setup = await renderApp();
+
+    // open the collapsed Threads sidebar first (its toggle sits three cells left of the brand); the
+    // brand rides the Thread header, which zoom then hides, so it must be reached before zooming
+    const brand = locateText(setup, "cueloop");
+
+    await setup.mockMouse.click(brand.column - 3, brand.row);
+    await waitForText(setup, "Zoomed Plan");
+
+    // zoom the diff - the Thread pane hides and the footer rides the Changes pane
+    const zoom = locateText(setup, NERD.zoom);
+
+    await setup.mockMouse.click(zoom.column, zoom.row);
+    await waitForState(setup, () => !setup.captureCharFrame().includes("Select a thread"));
+
+    // switch to the plan thread: it has no Changes editor, so a stranded zoom would blank the middle
+    const planRow = locateText(setup, "Zoomed Plan");
+
+    await setup.mockMouse.click(planRow.column, planRow.row);
+    await waitForText(setup, "Review this plan.");
+
+    const frame = setup.captureCharFrame();
+
+    // the Thread pane is back with the plan, and the diff's Changes editor is gone - never a blank middle
+    expect(frame).toContain("Review this plan.");
+    expect(frame).not.toContain("store.ts");
+  });
+
+  test("toggling the right sidebar while zoomed exits zoom and restores the Thread pane", async () => {
+    const setup = await renderApp();
+
+    // zoom the Changes editor - the Thread pane hides
+    const zoom = locateText(setup, NERD.zoom);
+
+    await setup.mockMouse.click(zoom.column, zoom.row);
+    await waitForState(setup, () => !setup.captureCharFrame().includes("Select a thread"));
+
+    // toggling the right sidebar off must not strand a blank screen: zoom exits, the Thread pane returns
+    await setup.mockMouse.click(rightToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "Select a thread");
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("Select a thread");
+    // the right region is collapsed and the Changes editor is gone
+    expect(frame).not.toContain("store.ts");
+    expect(diffToggleColumn(setup)).toBe(-1);
+  });
+
+  test("hovering the right-sidebar icon surfaces its tooltip label at the screen root", async () => {
+    const setup = await renderApp();
+
+    // the tip is not painted until the pointer is over the control
+    expect(setup.captureCharFrame()).not.toContain("Toggle Sidebar");
+
+    await setup.mockMouse.moveTo(rightToggleColumn(setup), HEADER_ROW);
+    // the label surfaces at the root, escaping the header cell that would otherwise clip it
+    await waitForText(setup, "Toggle Sidebar");
+  });
+});
+
+/** The bare-launch (no thread) shell is the same four panes as a thread: the Thread pane waits in its
+ * empty state and a disposable Welcome tab rides in the Changes editor. The right-region toggles behave
+ * like the thread shell, dismissing Welcome collapses the editor without stranding an empty screen, and
+ * a closed right region moves its reopen toggle into the header rather than leaving a gutter. */
+describe("the bare-launch welcome shell", () => {
+  let welcomeHome: string;
+  let welcomeRepo: string;
+  let restoreWelcome: () => void;
+  let welcomeServer: DaemonServer;
+
+  beforeEach(() => {
+    welcomeHome = mkdtempSync(join(tmpdir(), "cueloop-welcome-"));
+    // a small, controlled launch repo so the welcome tree/changes resolve fast and deterministically
+    welcomeRepo = makeRepo();
+    writeFileSync(join(welcomeRepo, "README.md"), "# Fixture\n\nedited in the working tree\n");
+    restoreWelcome = isolateUserConfig(welcomeHome);
+    welcomeServer = new DaemonServer({ home: welcomeHome, idleExitMs: 0 });
+    welcomeServer.start();
+  });
+  afterEach(() => {
+    restoreWelcome();
+    welcomeServer.stop();
+    rmSync(welcomeHome, { recursive: true, force: true });
+    rmSync(welcomeRepo, { recursive: true, force: true });
+  });
+
+  async function renderWelcome() {
+    const setup = await testRender(
+      <App home={welcomeHome} sessionId={undefined} cwd={welcomeRepo} />,
+      { width: 180, height: 14 },
+    );
+
+    await waitForText(setup, "cueloop");
+
+    return setup;
+  }
+
+  test("the project tree shows the launch repo's files even with no thread open", async () => {
+    const setup = await renderWelcome();
+
+    // the tree toggle loads the git repo the client launched in
+    await setup.mockMouse.click(treeToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "README.md");
+    expect(setup.captureCharFrame()).toContain("README.md");
+  });
+
+  test("Review shows only the skill selected in TOML", async () => {
+    writeFileSync(process.env.CUELOOP_CONFIG!, '[review]\nskill = "custom-review"\n');
+    const setup = await renderWelcome();
+
+    await setup.mockMouse.click(1, HEADER_ROW);
+    await waitForText(setup, "settings");
+    const settings = locateText(setup, "settings");
+
+    await setup.mockMouse.click(settings.column, settings.row);
+    await waitForText(setup, "General");
+    const review = locateText(setup, "Review");
+
+    await setup.mockMouse.click(review.column, review.row);
+    await waitForText(setup, "custom-review");
+    expect(setup.captureCharFrame()).not.toContain("research");
+    const skill = locateText(setup, "custom-review");
+
+    await setup.mockMouse.click(skill.column, skill.row);
+    expect(setup.captureCharFrame()).toContain("custom-review");
+    setup.renderer.destroy();
+  });
+
+  test("the first comment in the bare shell creates and persists a per-repo workbench thread", async () => {
+    const setup = await renderWelcome();
+
+    // open a project file in the bare shell (no thread yet - nothing on disk)
+    expect(welcomeServer.core.sessionList().length).toBe(0);
+    await setup.mockMouse.click(treeToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "README.md");
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForText(setup, "edited in the working tree");
+
+    // comment on a line - the first note find-or-creates the workbench thread
+    const line = "edited in the working tree";
+
+    await dragText(setup, line, line, line.length);
+    await typeText(setup, "workbench note");
+    await pressKey(setup, "RETURN", { meta: true });
+
+    // the daemon persisted one per-repo workbench thread carrying the note
+    await waitForState(setup, () =>
+      welcomeServer.core.sessionList().some((thread) => thread.artifact.meta.workbench === true),
+    );
+    const workbench = welcomeServer.core
+      .sessionList()
+      .find((thread) => thread.artifact.meta.workbench === true)!;
+
+    expect(workbench.workspace.rootCommit).toBeTruthy();
+    await waitForState(setup, () =>
+      welcomeServer.core
+        .sessionGet(workbench.id)
+        .annotations.some((note) => note.body.includes("workbench note")),
+    );
+  });
+
+  test("the changes tree lists the launch repo's working-tree changes", async () => {
+    const setup = await renderWelcome();
+
+    // changes mode is the default; the edited README shows with its status
+    await waitForText(setup, "README.md");
+    expect(setup.captureCharFrame()).toContain("README.md");
+  });
+
+  test("a changed file tab keeps copy and expand without a collapse action", async () => {
+    const setup = await renderWelcome();
+
+    await waitForText(setup, "README.md");
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForText(setup, "edited in the working tree");
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain(NERD.copy);
+    expect(frame).not.toContain("v README.md");
+    expect(frame).toContain("expand");
+    setup.renderer.destroy();
+  });
+
+  test("a bare changed-file tab uses Split only when zoomed in", async () => {
+    const setup = await renderWelcome();
+
+    await waitForText(setup, "README.md");
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForText(setup, "edited in the working tree");
+    const pairedLine = (line: string): boolean =>
+      line.includes("Workbench Fixture") && line.includes("+ # Fixture");
+
+    expect(setup.captureCharFrame().split("\n").some(pairedLine)).toBe(false);
+    const zoom = locateText(setup, NERD.zoom);
+
+    await setup.mockMouse.click(zoom.column, zoom.row);
+    await waitForState(setup, () => setup.captureCharFrame().split("\n").some(pairedLine));
+    expect(setup.captureCharFrame().split("\n").some(pairedLine)).toBe(true);
+    setup.renderer.destroy();
+  });
+
+  test("reopening Changes after dismissing Welcome keeps file actions", async () => {
+    const setup = await renderWelcome();
+    const welcome = locateText(setup, "Welcome");
+
+    await setup.mockMouse.click(welcome.column + 8, welcome.row);
+    await setup.mockMouse.click(diffToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "edited in the working tree");
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("README.md");
+    expect(frame).toContain(NERD.copy);
+    const title = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(title.column, title.row);
+    await waitForTextGone(setup, "edited in the working tree");
+    expect(setup.captureCharFrame()).toContain("README.md");
+    await setup.mockMouse.click(title.column, title.row);
+    await waitForText(setup, "edited in the working tree");
+    setup.renderer.destroy();
+  });
+
+  test("the changes tree clears after the launch repo becomes clean", async () => {
+    const setup = await renderWelcome();
+
+    await waitForText(setup, "README.md");
+    writeFileSync(join(welcomeRepo, "README.md"), "# Workbench Fixture\n\nA tiny tracked repo.\n");
+    await waitForState(setup, () => !setup.captureCharFrame().includes("README.md"));
+  });
+
+  test("a review layout opens the Changes panel, listing the working-tree changes", async () => {
+    const setup = await testRender(
+      <App home={welcomeHome} sessionId={undefined} cwd={welcomeRepo} layout={reviewLayout()} />,
+      { width: 180, height: 14 },
+    );
+
+    await waitForText(setup, "README.md");
+    expect(setup.captureCharFrame()).toContain("README.md");
+  });
+
+  test("a plan layout opens with the right region closed, so no Changes panel shows", async () => {
+    const setup = await testRender(
+      <App home={welcomeHome} sessionId={undefined} cwd={welcomeRepo} layout={planLayout()} />,
+      { width: 180, height: 14 },
+    );
+
+    await waitForText(setup, "cueloop");
+    // rightSidebar "off": neither the Changes list nor the launch repo's files paint
+    expect(setup.captureCharFrame()).not.toContain("README.md");
+  });
+
+  test("a hand-edited off+zoom layout drops the zoom so the center is not stranded blank", async () => {
+    // zoom fills the middle with the Changes editor; with the region off there is none, so honoring zoom
+    // would hide the Thread pane over a blank center. The Thread placeholder must still render.
+    const setup = await testRender(
+      <App
+        home={welcomeHome}
+        sessionId={undefined}
+        cwd={welcomeRepo}
+        layout={{ threads: true, rightSidebar: "off", zoomChanges: true }}
+      />,
+      { width: 180, height: 14 },
+    );
+
+    await waitForText(setup, "Select a thread");
+    expect(setup.captureCharFrame()).toContain("Select a thread");
+  });
+
+  test("closing the right region on the vanilla shell remembers it for the next launch", async () => {
+    const setup = await testRender(
+      <App
+        home={welcomeHome}
+        sessionId={undefined}
+        cwd={welcomeRepo}
+        layout={{ threads: true, rightSidebar: "changes", zoomChanges: false }}
+      />,
+      { width: 180, height: 14 },
+    );
+
+    await waitForText(setup, "README.md");
+
+    // close the Changes/Project region; the remembered layout follows it to "off"
+    await setup.mockMouse.click(rightToggleColumn(setup), HEADER_ROW);
+    await waitForState(
+      setup,
+      () =>
+        loadConfig({ userConfigPath: process.env.CUELOOP_CONFIG }).ui.layout?.rightSidebar ===
+        "off",
+    );
+    expect(loadConfig({ userConfigPath: process.env.CUELOOP_CONFIG }).ui.layout).toEqual({
+      threads: true,
+      rightSidebar: "off",
+      zoomChanges: false,
+    });
+  });
+
+  test("clicking a changed file in the bare shell opens its diff, not its contents", async () => {
+    const setup = await renderWelcome();
+
+    await waitForText(setup, "README.md");
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+
+    // a diff shows both the removed old line and the added new line; contents would show only the new
+    await waitForText(setup, "A tiny tracked repo.");
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("A tiny tracked repo.");
+    expect(frame).toContain("edited in the working tree");
+  });
+
+  test("nav mode on the Welcome tab offers only comment and fold; a diff letter types", async () => {
+    const setup = await renderReadyApp(
+      <App home={welcomeHome} sessionId={undefined} cwd={welcomeRepo} />,
+      { width: 160, height: 28 },
+    );
+
+    await waitForText(setup, "quick brown fox");
+    const line = locateText(setup, "quick brown fox");
+
+    await setup.mockMouse.click(line.column, line.row);
+
+    // esc enters nav; the footer names what this surface can do, not the diff commands
+    await press(setup, "escape");
+    await waitForText(setup, BARE_NAV_HINT);
+    expect(setup.captureCharFrame()).not.toContain("x reject");
+
+    // a diff letter has no command here, so it leaves nav and types, as the footer says
+    await pressKey(setup, "d");
+    await waitForText(setup, "● d");
+    await press(setup, "escape");
+    await waitForTextGone(setup, "● d");
+
+    // c opens a comment on the caret word; z folds the saved card
+    await press(setup, "escape");
+    await waitForText(setup, BARE_NAV_HINT);
+    await pressKey(setup, "c");
+    await typeText(setup, "note");
+    await waitForText(setup, "● note");
+    await pressKey(setup, "RETURN", { meta: true });
+    await waitForText(setup, "note");
+    await press(setup, "escape");
+    await waitForText(setup, BARE_NAV_HINT);
+    await pressKey(setup, "z");
+    await waitForText(setup, "○ 1 comment ›");
+
+    setup.renderer.destroy();
+  });
+
+  test("nav mode on a bare changed-file diff has no reject or walk; x types instead", async () => {
+    const setup = await renderReadyApp(
+      <App home={welcomeHome} sessionId={undefined} cwd={welcomeRepo} />,
+      { width: 160, height: 28 },
+    );
+
+    await waitForText(setup, "README.md");
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForText(setup, "edited in the working tree");
+    const line = locateText(setup, "edited in the working tree");
+
+    await setup.mockMouse.click(line.column, line.row);
+
+    await press(setup, "escape");
+    await waitForText(setup, BARE_NAV_HINT);
+    expect(setup.captureCharFrame()).not.toContain("x reject");
+    await pressKey(setup, "x");
+    await waitForText(setup, "● x");
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("edited in the working tree");
+    expect(frame).not.toContain("change rejected");
+
+    setup.renderer.destroy();
+  });
+
+  test("nav mode on a project file offers only comment and fold", async () => {
+    const setup = await renderReadyApp(
+      <App home={welcomeHome} sessionId={undefined} cwd={welcomeRepo} />,
+      { width: 160, height: 28 },
+    );
+
+    await waitForText(setup, "README.md");
+    await setup.mockMouse.click(treeToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "README.md");
+    const readme = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(readme.column, readme.row);
+    await waitForText(setup, "edited in the working tree");
+    const line = locateText(setup, "edited in the working tree");
+
+    await setup.mockMouse.click(line.column, line.row);
+
+    await press(setup, "escape");
+    await waitForText(setup, BARE_NAV_HINT);
+    expect(setup.captureCharFrame()).not.toContain("x reject");
+    await pressKey(setup, "d");
+    await waitForText(setup, "● d");
+
+    setup.renderer.destroy();
+  });
+
+  test("a bare launch rides a Welcome tab in the editor while the Thread pane waits empty", async () => {
+    const setup = await renderWelcome();
+
+    // the Welcome playground measures its width before it paints, so wait for its copy
+    await waitForText(setup, "Getting started");
+    const frame = setup.captureCharFrame();
+
+    // the getting-started surface is an editor tab, not the thread pane
+    expect(frame.split("\n")[HEADER_ROW]!).toContain("Welcome");
+    expect(frame).toContain("Getting started");
+    // the Thread pane shows its empty state until a thread is opened
+    expect(frame).toContain("Select a thread");
+  });
+
+  test("the Threads sidebar owns the keyboard until a pane is clicked, so nav never touches the editor", async () => {
+    const setup = await renderReadyApp(
+      <App home={welcomeHome} sessionId={undefined} cwd={welcomeRepo} />,
+      { width: 160, height: 24 },
+    );
+
+    await waitForText(setup, "Getting started");
+
+    // focus starts on the Threads sidebar: a letter drives the inbox, it never drafts in the editor
+    await typeText(setup, "zzz");
+    expect(setup.captureCharFrame()).not.toContain("zzz");
+
+    // clicking a line in the Welcome editor focuses that pane; now typing composes there
+    const line = locateText(setup, "quick brown fox");
+
+    await setup.mockMouse.click(line.column, line.row);
+    await typeText(setup, "note");
+    await waitForText(setup, "● note");
+
+    setup.renderer.destroy();
+  });
+
+  test("typing in the welcome composer never reaches the inbox keys", async () => {
+    // a pending thread in the sidebar so the inbox keys (delete, open) have a target to act on
+    welcomeServer.core.sessionCreate({
+      workspace: { repoRoot: welcomeRepo, branch: "main" },
+      artifact: { type: "plan", content: "# Seeded\n", meta: { title: "Seeded Plan" } },
+    });
+    const setup = await testRender(
+      <App home={welcomeHome} sessionId={undefined} cwd={welcomeRepo} />,
+      { width: 160, height: 28 },
+    );
+
+    await waitForText(setup, "quick brown fox");
+
+    // open the playground composer, then type letters that are also inbox keys (j, k, d), one at a
+    // time as a person would - each keystroke settles a frame, the way real input arrives
+    await dragText(setup, "quick brown fox", "quick brown fox", "quick brown fox".length);
+    for (const character of "note: jkd") await typeText(setup, character);
+    await waitForText(setup, "note: jkd");
+
+    // the letters landed in the note, not the inbox: no delete confirmation opened
+    expect(setup.captureCharFrame()).not.toContain("This removes the plan");
+
+    // Cmd+Enter saves the note; it must not dispatch openSession and replace the playground
+    await pressKey(setup, "RETURN", { meta: true });
+    expect(setup.captureCharFrame()).toContain("Getting started");
+
+    setup.renderer.destroy();
+  });
+
+  test("dismissing the Welcome tab collapses the editor without stranding an empty screen", async () => {
+    const setup = await renderWelcome();
+
+    const welcome = locateText(setup, "Welcome");
+
+    // the close box sits just past the label
+    await setup.mockMouse.click(welcome.column + 8, welcome.row);
+    await waitForState(
+      setup,
+      () => !setup.captureCharFrame().includes("comment on agent-authored work"),
+    );
+
+    // the Threads sidebar and the Thread empty state remain - never a blank shell
+    const frame = setup.captureCharFrame();
+
+    expect(frame).toContain("cueloop");
+    expect(frame).toContain("Select a thread");
+  });
+
+  test("the changed-files and tree toggles switch navigator mode without collapsing", async () => {
+    const setup = await renderWelcome();
+
+    expect(diffToggleColumn(setup)).toBeGreaterThan(0);
+
+    // the tree toggle switches to the project view (the launch repo's tree) without collapsing
+    await setup.mockMouse.click(treeToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "src");
+    expect(diffToggleColumn(setup)).toBeGreaterThan(0);
+
+    // the changed-files toggle switches back, still open
+    await setup.mockMouse.click(diffToggleColumn(setup), HEADER_ROW);
+    await waitForState(setup, () => !setup.captureCharFrame().includes("src"));
+    expect(diffToggleColumn(setup)).toBeGreaterThan(0);
+
+    // the sidebar toggle closes the region
+    await setup.mockMouse.click(rightToggleColumn(setup), HEADER_ROW);
+    await waitForState(setup, () => diffToggleColumn(setup) === -1);
+  });
+
+  test("the changes sidebar label opens one Changes tab beside Welcome and reactivates it", async () => {
+    const setup = await renderWelcome();
+
+    await setup.mockMouse.click(diffToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "edited in the working tree");
+    const firstHeader = setup.captureCharFrame().split("\n")[HEADER_ROW]!;
+
+    expect(firstHeader).toContain("Welcome");
+    expect(firstHeader).toContain("Changes");
+
+    const welcome = locateText(setup, "Welcome");
+
+    await setup.mockMouse.click(welcome.column, welcome.row);
+    await waitForText(setup, "Getting started");
+    await setup.mockMouse.click(diffToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "edited in the working tree");
+    expect(
+      setup
+        .captureCharFrame()
+        .split("\n")
+        [HEADER_ROW]!.match(/Changes/g),
+    ).toHaveLength(1);
+    setup.renderer.destroy();
+  });
+
+  test("the changes sidebar label activates Changes beside an open file tab", async () => {
+    const setup = await renderWelcome();
+
+    await waitForText(setup, "README.md");
+    const file = locateText(setup, "README.md");
+
+    await setup.mockMouse.click(file.column, file.row);
+    await waitForText(setup, "README.md");
+    await setup.mockMouse.click(diffToggleColumn(setup), HEADER_ROW);
+    await waitForText(setup, "edited in the working tree");
+    const header = setup.captureCharFrame().split("\n")[HEADER_ROW]!;
+
+    expect(header).toContain("Welcome");
+    expect(header).toContain("README.md");
+    expect(header).toContain("Changes");
+    setup.renderer.destroy();
+  });
+
+  test("a closed region draws its reopen divider in the header only, not full-height", async () => {
+    const setup = await renderWelcome();
+
+    // close the right region so only the header toggle remains
+    await setup.mockMouse.click(rightToggleColumn(setup), HEADER_ROW);
+    await waitForState(setup, () => diffToggleColumn(setup) === -1);
+
+    const lines = setup.captureCharFrame().split("\n");
+    // the reopen toggle's divider sits at the far right; find its column on the header row
+    const headerDivider = lines[HEADER_ROW]!.lastIndexOf("│");
+
+    expect(headerDivider).toBeGreaterThan(0);
+    // that column stays clear below the two-row header - no full-height column rule
+    const bodyRows = lines.slice(3).filter((line) => line.length > headerDivider);
+
+    expect(bodyRows.length).toBeGreaterThan(0);
+    for (const line of bodyRows) {
+      expect(line[headerDivider]).not.toBe("│");
+    }
+  });
+});