Improve sidebar workspace readability and host identity (#2790)

* fix(app): align turn footer actions Keep running-turn actions in the same position as completed-turn actions and use the shared small icon size for both copy and fork controls. * feat(app): improve sidebar workspace identity Make dense sidebar workspace rows easier to scan and let each device control how connected hosts are identified. * fix(app): keep host badges readable Use a compact display menu and keep identity color on the host icon so translated controls fit and badge text retains standard contrast. * fix(app): announce selected sidebar badge mode * fix(app): retain icon-only host names for screen readers * fix(app): name hoisted workspace rows * fix(app): retain host identity in workspace labels * fix(app): retain workspace status in row labels * fix(app): defer host appearance until identity resolves * fix(app): serialize host appearance writes * fix(app): serialize host registry writes * fix(app): bound sidebar host badge labels * test(app): match workspace status labels * fix(app): consolidate sidebar identity behavior * test(app): assert status grouping behavior * fix(app): keep sidebar row actions accessible * fix(app): stabilize optimistic message layout
2026-08-02 16:58:20 +02:00
parent 553ac53643
commit ccb668b3b4
57 changed files with 3251 additions and 809 deletions
@@ -660,6 +660,19 @@ function expectAtomicIdleToRunningTransition(frames: TurnFrame[]): void {
  ).toEqual([]);
 }

+function expectSubmittedMessageHeightStable(frames: TurnFrame[]): void {
+  const first = frames.findIndex((frame) => frame.userRow.visible);
+  const baseline = frames[first]?.userRow.rect?.height;
+  const changes = frames
+    .slice(first)
+    .flatMap((frame, offset) =>
+      geometryChanged(frame.userRow.rect?.height, baseline)
+        ? [`frame ${first + offset}: submitted row height changed`]
+        : [],
+    );
+  expect(changes, `submitted message geometry changed:\n${changes.join("\n")}`).toEqual([]);
+}
+
 function expectAtomicFirstPromptTransition(frames: TurnFrame[]): void {
  expectRowContinuity(frames);
  const first = frames.findIndex((frame) => hasPaintedLayout(frame.userRow));
@@ -828,6 +841,33 @@ test("keeps follow-up activity continuous when turn starts before response", asy
  expectAtomicIdleToRunningTransition(frames);
 });

+test("keeps a submitted message height stable when its canonical echo arrives", async ({
+  page,
+  streamingAgent,
+}) => {
+  const gate = await installDaemonWebSocketGate(page);
+  await openAgentRoute(page, {
+    workspaceId: streamingAgent.workspaceId,
+    agentId: streamingAgent.agentId,
+  });
+  await expectAgentIdle(page);
+
+  const prompt = "Canonical echo must not resize this message.";
+  gate.holdNextAgentStreamItem("user_message");
+  await recordTurnFrames(page, prompt);
+  await submitMessage(page, prompt);
+  await gate.waitForHeldAgentStreamItem("user_message");
+  const submittedRow = page.getByTestId("user-message").filter({ hasText: prompt });
+  await expect(submittedRow).toBeVisible();
+  await recordPaintsFor(page, 80);
+
+  gate.releaseHeldAgentStreamItem("user_message");
+  await expect(submittedRow.getByTestId("rewind-menu-trigger")).toBeVisible();
+  await recordPaintsFor(page, 80);
+
+  expectSubmittedMessageHeightStable(await stopTurnFrameRecording(page));
+});
+
 test("keeps follow-up activity continuous when response arrives before running state", async ({
  page,
  streamingAgent,
@@ -0,0 +1,212 @@
+import { expect, test as base } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import {
+  addConnectedHostAndReload,
+  chooseHostBadgeDisplay,
+  chooseHostColor,
+  expectHostAppearancePreview,
+  expectHostBadgeIconOnly,
+  expectHostBadgeName,
+  expectHostBadgeTinted,
+  expectNoHostBadge,
+  leaveHostAppearanceSettings,
+  openHostAppearanceSettings,
+  reloadPreservingHostRegistry,
+  renameHostFromSettings,
+  waitForConnectedHost,
+} from "../support/helpers/hosts";
+import {
+  type IsolatedHostDaemon,
+  startIsolatedHostDaemon,
+} from "../support/helpers/isolated-host-daemon";
+import { seedWorkspace, type SeededWorkspace } from "../support/helpers/seed-client";
+import { getServerId } from "../support/helpers/server-id";
+import { waitForSidebarHydration } from "../support/helpers/workspace-ui";
+
+const PRIMARY_HOST_LABEL = "Primary Host";
+const SECONDARY_HOST_LABEL = "Secondary Host";
+
+interface TwoHostSidebar {
+  primaryServerId: string;
+  primaryWorkspaceId: string;
+  secondaryServerId: string;
+  secondaryWorkspaceId: string;
+}
+
+// The host badge only appears once the visible sidebar spans more than one host, and that count
+// runs over visible projects — so an offline host with no workspaces will not raise it. Two real
+// daemons, each with a seeded workspace, is the minimum shape that exercises the feature.
+const test = base.extend<{ twoHostSidebar: TwoHostSidebar }>({
+  twoHostSidebar: async ({ page }, provide) => {
+    const secondaryHost: IsolatedHostDaemon = await startIsolatedHostDaemon(
+      "host-appearance-secondary",
+    );
+    let primary: SeededWorkspace | null = null;
+    let secondary: SeededWorkspace | null = null;
+
+    try {
+      primary = await seedWorkspace({
+        repoPrefix: "host-appearance-primary-",
+        title: "Primary workspace",
+      });
+      secondary = await seedWorkspace({
+        repoPrefix: "host-appearance-secondary-",
+        title: "Secondary workspace",
+        port: secondaryHost.port,
+      });
+
+      await gotoAppShell(page);
+      await addConnectedHostAndReload(page, {
+        serverId: secondaryHost.serverId,
+        label: SECONDARY_HOST_LABEL,
+        port: secondaryHost.port,
+        primaryLabel: PRIMARY_HOST_LABEL,
+      });
+      await waitForConnectedHost(page, {
+        serverId: secondaryHost.serverId,
+        endpoint: `localhost:${secondaryHost.port}`,
+      });
+      await waitForSidebarHydration(page);
+
+      await provide({
+        primaryServerId: getServerId(),
+        primaryWorkspaceId: primary.workspaceId,
+        secondaryServerId: secondaryHost.serverId,
+        secondaryWorkspaceId: secondary.workspaceId,
+      });
+    } finally {
+      await primary?.cleanup().catch(() => undefined);
+      await secondary?.cleanup().catch(() => undefined);
+      await secondaryHost.close().catch(() => undefined);
+    }
+  },
+});
+
+test.describe("Host appearance", () => {
+  test.describe.configure({ timeout: 180_000 });
+
+  test("renaming a host renames its sidebar badge", async ({ page, twoHostSidebar }) => {
+    const badge = {
+      serverId: twoHostSidebar.secondaryServerId,
+      workspaceId: twoHostSidebar.secondaryWorkspaceId,
+    };
+    await expectHostBadgeName(page, { ...badge, hostName: SECONDARY_HOST_LABEL });
+
+    await openHostAppearanceSettings(page, twoHostSidebar.secondaryServerId);
+    await renameHostFromSettings(page, "Build Box");
+    await leaveHostAppearanceSettings(page);
+
+    await expectHostBadgeName(page, { ...badge, hostName: "Build Box" });
+  });
+
+  test("long host names leave room for the workspace title and actions", async ({
+    page,
+    twoHostSidebar,
+  }) => {
+    const hostName = "A very long remote build host name that must not take over the sidebar";
+    const workspaceKey = `${twoHostSidebar.secondaryServerId}:${twoHostSidebar.secondaryWorkspaceId}`;
+
+    await openHostAppearanceSettings(page, twoHostSidebar.secondaryServerId);
+    await renameHostFromSettings(page, hostName);
+    await leaveHostAppearanceSettings(page);
+
+    const row = page.getByTestId(`sidebar-workspace-row-${workspaceKey}`);
+    const badge = row.getByTestId(`sidebar-host-badge-${twoHostSidebar.secondaryServerId}`);
+    await expect(badge).toHaveText(hostName);
+    await row.hover();
+
+    const title = row.getByText("Secondary workspace", { exact: true });
+    const kebab = page.getByTestId(`sidebar-workspace-kebab-${workspaceKey}`);
+    await expect(kebab).toBeVisible();
+    const [badgeBox, titleBox, rowBox, kebabBox] = await Promise.all([
+      badge.boundingBox(),
+      title.boundingBox(),
+      row.boundingBox(),
+      kebab.boundingBox(),
+    ]);
+
+    expect(badgeBox).not.toBeNull();
+    expect(titleBox).not.toBeNull();
+    expect(rowBox).not.toBeNull();
+    expect(kebabBox).not.toBeNull();
+    expect(titleBox!.width).toBeGreaterThan(0);
+    expect(kebabBox!.x + kebabBox!.width).toBeLessThanOrEqual(rowBox!.x + rowBox!.width);
+  });
+
+  test("picking a color identifies the badge", async ({ page, twoHostSidebar }) => {
+    const badge = {
+      serverId: twoHostSidebar.secondaryServerId,
+      workspaceId: twoHostSidebar.secondaryWorkspaceId,
+      hostName: SECONDARY_HOST_LABEL,
+    };
+
+    await openHostAppearanceSettings(page, twoHostSidebar.secondaryServerId);
+    await chooseHostColor(page, "Teal");
+    await leaveHostAppearanceSettings(page);
+
+    await expectHostBadgeTinted(page, { ...badge, color: "teal" });
+  });
+
+  test("icon only keeps the badge and drops the name", async ({ page, twoHostSidebar }) => {
+    const badge = {
+      serverId: twoHostSidebar.secondaryServerId,
+      workspaceId: twoHostSidebar.secondaryWorkspaceId,
+      hostName: SECONDARY_HOST_LABEL,
+    };
+
+    await openHostAppearanceSettings(page, twoHostSidebar.secondaryServerId);
+    await chooseHostBadgeDisplay(page, "Icon only");
+    await leaveHostAppearanceSettings(page);
+
+    await expectHostBadgeIconOnly(page, badge);
+  });
+
+  test("hiding one host leaves the other host's badge visible", async ({
+    page,
+    twoHostSidebar,
+  }) => {
+    await openHostAppearanceSettings(page, twoHostSidebar.secondaryServerId);
+    await chooseHostBadgeDisplay(page, "Hidden");
+    await leaveHostAppearanceSettings(page);
+
+    await expectNoHostBadge(page, {
+      serverId: twoHostSidebar.secondaryServerId,
+      workspaceId: twoHostSidebar.secondaryWorkspaceId,
+      hostName: SECONDARY_HOST_LABEL,
+    });
+    await expectHostBadgeName(page, {
+      serverId: twoHostSidebar.primaryServerId,
+      workspaceId: twoHostSidebar.primaryWorkspaceId,
+      hostName: PRIMARY_HOST_LABEL,
+    });
+  });
+
+  test("name, color, and display survive a reload", async ({ page, twoHostSidebar }) => {
+    await openHostAppearanceSettings(page, twoHostSidebar.secondaryServerId);
+    await renameHostFromSettings(page, "Build Box");
+    await chooseHostColor(page, "Amber");
+    await chooseHostBadgeDisplay(page, "Icon only");
+    await leaveHostAppearanceSettings(page);
+
+    await reloadPreservingHostRegistry(page);
+    await waitForSidebarHydration(page);
+
+    await expectHostBadgeIconOnly(page, {
+      serverId: twoHostSidebar.secondaryServerId,
+      workspaceId: twoHostSidebar.secondaryWorkspaceId,
+      hostName: "Build Box",
+    });
+  });
+
+  test("the settings preview shows the badge as configured", async ({ page, twoHostSidebar }) => {
+    await openHostAppearanceSettings(page, twoHostSidebar.secondaryServerId);
+    await renameHostFromSettings(page, "Build Box");
+    await chooseHostColor(page, "Emerald");
+
+    await expectHostAppearancePreview(page, {
+      serverId: twoHostSidebar.secondaryServerId,
+      hostName: "Build Box",
+      color: "emerald",
+    });
+  });
+});
@@ -116,7 +116,13 @@ async function startTrackingSidebarStatusGroups(page: import("@playwright/test")

    capture();
    const observer = new MutationObserver(capture);
-    observer.observe(document.body, { childList: true, subtree: true, characterData: true });
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: true,
+      attributeFilter: ["data-testid"],
+    });
    win.__workspaceStatusGroupObserver = observer;
  });
 }
@@ -159,7 +165,6 @@ async function expectWorkspaceStatusGroupEvents(input: {
  rowTestId: string;
  includes: string;
  excludes: string;
-  includesIndicator?: string;
  excludesIndicator?: string;
 }) {
  await waitForWorkspaceStatusGroupEvent({
@@ -172,11 +177,6 @@ async function expectWorkspaceStatusGroupEvents(input: {
  );
  expect(createdWorkspaceEvents.map((event) => event.bucket)).toContain(input.includes);
  expect(createdWorkspaceEvents.filter((event) => event.bucket === input.excludes)).toEqual([]);
-  if (input.includesIndicator) {
-    expect(createdWorkspaceEvents.map((event) => event.indicatorTestId)).toContain(
-      input.includesIndicator,
-    );
-  }
  if (input.excludesIndicator) {
    expect(
      createdWorkspaceEvents.filter((event) => event.indicatorTestId === input.excludesIndicator),
@@ -612,7 +612,6 @@ test.describe("New workspace flow", () => {
        rowTestId,
        includes: "running",
        excludes: "done",
-        includesIndicator: "workspace-status-indicator-running",
      });
    } finally {
      await tempRepo.cleanup();
@@ -0,0 +1,40 @@
+import { test } from "../support/fixtures";
+import { gotoAppShell } from "../support/helpers/app";
+import { seedWorkspace } from "../support/helpers/seed-client";
+import {
+  closeProjectContextMenu,
+  closeWorkspaceContextMenu,
+  expectProjectContextMenuActions,
+  expectWorkspaceContextMenuActions,
+  expectWorkspaceContextMenuOwnsAttention,
+  expectWorkspaceRowHoverCleared,
+  openProjectContextMenu,
+  openWorkspaceContextMenu,
+  showWorkspaceHoverCard,
+} from "../support/helpers/sidebar";
+
+test.describe("Sidebar context menus", () => {
+  test("right-clicking workspace and project rows opens their actions at the pointer", async ({
+    page,
+  }) => {
+    const workspace = await seedWorkspace({ repoPrefix: "sidebar-context-menu-" });
+
+    try {
+      await gotoAppShell(page);
+
+      await showWorkspaceHoverCard(page, workspace.workspaceId);
+      await openWorkspaceContextMenu(page, workspace.workspaceId);
+      await expectWorkspaceContextMenuActions(page, workspace.workspaceId);
+      await expectWorkspaceContextMenuOwnsAttention(page);
+
+      await closeWorkspaceContextMenu(page, workspace.workspaceId);
+      await expectWorkspaceRowHoverCleared(page, workspace.workspaceId);
+      await openProjectContextMenu(page, workspace.projectKey);
+      await expectProjectContextMenuActions(page, workspace.projectKey);
+
+      await closeProjectContextMenu(page, workspace.projectKey);
+    } finally {
+      await workspace.cleanup();
+    }
+  });
+});
@@ -149,6 +149,12 @@ test.describe("Model B sidebar shape", () => {
      await expect(workspaceRow(page, activeMock.workspaceId).first()).toBeVisible({
        timeout: 60_000,
      });
+      await expect(workspaceRow(page, idleProject.workspaceId).first()).toHaveAccessibleName(
+        `${idleProject.projectDisplayName}, ${idleProject.workspaceName}`,
+      );
+      await expect(workspaceRow(page, activeMock.workspaceId).first()).toHaveAccessibleName(
+        /Working$/,
+      );

      // Only workspace rows are shown — no tab/agent/terminal leaves leak into
      // the status view.
@@ -102,5 +102,11 @@ function projectRow(page: Page, project: StatusProject) {
 }

 function workspaceRow(page: Page, workspaceName: string) {
-  return page.getByRole("button", { name: workspaceName, exact: true });
+  return page.getByRole("button", {
+    name: new RegExp(`^${escapeRegExp(workspaceName)}(?:,|$)`),
+  });
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -176,6 +176,10 @@ function agentStreamEventKey(type: string): string {
  return `agent-stream-event:${type}`;
 }

+function agentStreamItemKey(type: string): string {
+  return `agent-stream-item:${type}`;
+}
+
 function agentUpdateKey(agentId: string, status: string): string {
  return `agent-update:${agentId}:${status}`;
 }
@@ -526,6 +530,12 @@ export async function installDaemonWebSocketGate(page: Page) {
        (message) => readAgentStreamEventType(message) === type,
      );
    },
+    holdNextAgentStreamItem(type: string): void {
+      pendingServerMessageHolds.set(
+        agentStreamItemKey(type),
+        (message) => readAgentStreamItemType(message) === type,
+      );
+    },
    async waitForHeldServerMessage(type?: string): Promise<void> {
      const key = type ? serverMessageKey(type) : null;
      while (!heldServerMessages.some((message) => key === null || message.key === key)) {
@@ -574,6 +584,22 @@ export async function installDaemonWebSocketGate(page: Page) {
        heldServerMessage.browser.send(follower);
      }
    },
+    async waitForHeldAgentStreamItem(type: string): Promise<void> {
+      const key = agentStreamItemKey(type);
+      while (!heldServerMessages.some((message) => message.key === key)) {
+        await new Promise<void>((resolve) => heldServerMessageWaiters.add(resolve));
+      }
+    },
+    releaseHeldAgentStreamItem(type: string): void {
+      const key = agentStreamItemKey(type);
+      const index = heldServerMessages.findIndex((message) => message.key === key);
+      const [heldServerMessage] = index >= 0 ? heldServerMessages.splice(index, 1) : [];
+      if (!heldServerMessage) throw new Error("No held agent stream item to release");
+      heldServerMessage.browser.send(heldServerMessage.message);
+      for (const follower of heldServerMessage.agentStreamFollowers) {
+        heldServerMessage.browser.send(follower);
+      }
+    },
    requestTimelineTail(agentId: string): void {
      if (!latestServer) throw new Error("No daemon WebSocket is connected");
      latestServer.send(
@@ -1,5 +1,8 @@
 import { expect, type Page } from "@playwright/test";
+import { identityColor, type IdentityColorName } from "@/styles/identity-colors";
+import { openSettings } from "./app";
 import { buildSeededHost } from "./daemon-registry";
+import { clickSettingsBackToWorkspace, openHostSection, selectSettingsHost } from "./settings";

 const REGISTRY_KEY = "@paseo:daemon-registry";
 const SEED_NONCE_KEY = "@paseo:e2e-seed-nonce";
@@ -140,3 +143,113 @@ export async function toggleHostFilter(page: Page, serverId: string): Promise<vo
 export async function selectAllHostsFilter(page: Page): Promise<void> {
  await page.getByTestId("sidebar-host-filter-all").click();
 }
+
+export async function openHostAppearanceSettings(page: Page, serverId: string): Promise<void> {
+  await openSettings(page);
+  await selectSettingsHost(page, serverId);
+  await openHostSection(page, serverId, "host");
+  await expect(page.getByTestId("host-appearance-preview")).toBeVisible({ timeout: 15_000 });
+}
+
+// Settings replaces the workspace sidebar, so badge assertions need the app shell back. Going
+// through the in-app back control (rather than a fresh goto) also keeps the auto-seed fixture
+// from rewriting the host registry, since init scripts only re-run on a real navigation.
+export async function leaveHostAppearanceSettings(page: Page): Promise<void> {
+  await clickSettingsBackToWorkspace(page);
+  await expect(page.getByTestId("host-appearance-preview")).toHaveCount(0);
+}
+
+export async function renameHostFromSettings(page: Page, name: string): Promise<void> {
+  await page.getByTestId("host-page-label-edit-button").click();
+  const input = page.getByTestId("host-page-rename-modal-input");
+  await expect(input).toBeVisible();
+  await input.fill(name);
+  await page.getByTestId("host-page-rename-modal-submit").click();
+  await expect(input).toHaveCount(0);
+}
+
+export async function chooseHostColor(page: Page, colorName: string): Promise<void> {
+  await page.getByRole("button", { name: /^Color, / }).click();
+  await page.getByRole("button", { name: colorName, exact: true }).click();
+  await expect(page.getByRole("button", { name: `Color, ${colorName}` })).toBeVisible();
+}
+
+export async function chooseHostBadgeDisplay(
+  page: Page,
+  option: "Name" | "Icon only" | "Hidden",
+): Promise<void> {
+  await page.getByTestId("host-appearance-badge-display").click();
+  await page.getByRole("button", { name: option, exact: true }).click();
+  await expect(page.getByRole("button", { name: `Sidebar badge, ${option}` })).toBeVisible();
+}
+
+// The badge is visual-only; the workspace row owns its accessible name. Test IDs keep visual
+// assertions from coupling to that row-level accessibility contract.
+function hostBadge(page: Page, input: HostBadgeTarget) {
+  return page
+    .getByTestId(`sidebar-workspace-row-${input.serverId}:${input.workspaceId}`)
+    .getByTestId(`sidebar-host-badge-${input.serverId}`);
+}
+
+interface HostBadgeTarget {
+  serverId: string;
+  workspaceId: string;
+  hostName: string;
+}
+
+export async function expectHostBadgeName(page: Page, target: HostBadgeTarget): Promise<void> {
+  const badge = hostBadge(page, target);
+  await expect(badge).toBeVisible({ timeout: 15_000 });
+  await expect(badge).toHaveText(target.hostName);
+}
+
+export async function expectHostBadgeIconOnly(page: Page, target: HostBadgeTarget): Promise<void> {
+  const badge = hostBadge(page, target);
+  await expect(badge).toBeVisible({ timeout: 15_000 });
+  await expect(badge).not.toHaveText(target.hostName);
+  await expect(
+    page.getByTestId(`sidebar-workspace-row-${target.serverId}:${target.workspaceId}`),
+  ).toHaveAccessibleName(new RegExp(target.hostName));
+}
+
+export async function expectNoHostBadge(page: Page, target: HostBadgeTarget): Promise<void> {
+  await expect(hostBadge(page, target)).toHaveCount(0, { timeout: 15_000 });
+}
+
+export async function expectHostBadgeTinted(
+  page: Page,
+  target: HostBadgeTarget & { color: IdentityColorName },
+): Promise<void> {
+  const badge = hostBadge(page, target);
+  await expect(badge).toBeVisible({ timeout: 15_000 });
+  await expect(badge.getByText(target.hostName)).toHaveCSS("color", "rgb(113, 113, 122)");
+  await expect(badge.locator("svg")).toHaveAttribute("stroke", identityColor(target.color));
+}
+
+export async function expectHostAppearancePreview(
+  page: Page,
+  input: { serverId: string; hostName: string; color: IdentityColorName },
+): Promise<void> {
+  const preview = page.getByTestId("host-appearance-preview");
+  await expect(preview).toBeVisible();
+  const badge = preview.getByTestId(`sidebar-host-badge-${input.serverId}`);
+  await expect(badge).toHaveText(input.hostName);
+  await expect(badge.locator("svg")).toHaveAttribute("stroke", identityColor(input.color));
+}
+
+// The auto-seed fixture rewrites the host registry on every navigation. Setting the
+// disable-once flag to the current nonce makes it skip exactly one reload, which is what proves
+// the appearance survived rather than being reseeded.
+export async function reloadPreservingHostRegistry(page: Page): Promise<void> {
+  await page.evaluate(
+    (keys) => {
+      const nonce = localStorage.getItem(keys.nonce);
+      if (!nonce) {
+        throw new Error("Expected the e2e seed nonce before reloading.");
+      }
+      localStorage.setItem(keys.disableSeedOnce, nonce);
+    },
+    { nonce: SEED_NONCE_KEY, disableSeedOnce: DISABLE_DEFAULT_SEED_ONCE_KEY },
+  );
+  await page.reload();
+}
@@ -1,6 +1,110 @@
 import { expect, type Page } from "@playwright/test";
 import { getServerId } from "./server-id";

+interface ContextMenuAnchor {
+  x: number;
+  y: number;
+}
+
+async function openContextMenuAtRowPoint(
+  page: Page,
+  rowTestID: string,
+  menuTestID: string,
+): Promise<ContextMenuAnchor> {
+  const row = page.getByTestId(rowTestID);
+  await expect(row).toBeVisible({ timeout: 30_000 });
+  const bounds = await row.boundingBox();
+  if (!bounds) throw new Error(`Could not measure ${rowTestID}`);
+
+  const anchor = {
+    x: bounds.x + Math.min(60, bounds.width / 2),
+    y: bounds.y + bounds.height / 2,
+  };
+  await page.mouse.click(anchor.x, anchor.y, { button: "right" });
+  await expect(page.getByTestId(menuTestID)).toBeVisible({ timeout: 10_000 });
+  return anchor;
+}
+
+async function expectContextMenuAtPointer(
+  page: Page,
+  menuTestID: string,
+  anchor: ContextMenuAnchor,
+): Promise<void> {
+  const bounds = await page.getByTestId(menuTestID).boundingBox();
+  if (!bounds) throw new Error(`Could not measure ${menuTestID}`);
+  expect(Math.abs(bounds.x - anchor.x)).toBeLessThanOrEqual(2);
+  expect(Math.abs(bounds.y - (anchor.y + 4))).toBeLessThanOrEqual(2);
+}
+
+export async function openWorkspaceContextMenu(page: Page, workspaceId: string): Promise<void> {
+  const workspaceKey = `${getServerId()}:${workspaceId}`;
+  const menuTestID = `sidebar-workspace-context-menu-${workspaceKey}`;
+  const anchor = await openContextMenuAtRowPoint(
+    page,
+    `sidebar-workspace-row-${workspaceKey}`,
+    menuTestID,
+  );
+  await expectContextMenuAtPointer(page, menuTestID, anchor);
+}
+
+export async function showWorkspaceHoverCard(page: Page, workspaceId: string): Promise<void> {
+  const workspaceKey = `${getServerId()}:${workspaceId}`;
+  await page.getByTestId(`sidebar-workspace-row-${workspaceKey}`).hover();
+  await expect(page.getByTestId("workspace-hover-card")).toBeVisible();
+}
+
+export async function closeWorkspaceContextMenu(page: Page, workspaceId: string): Promise<void> {
+  const workspaceKey = `${getServerId()}:${workspaceId}`;
+  await page.getByTestId(`sidebar-workspace-context-menu-${workspaceKey}-backdrop`).click();
+}
+
+export async function expectWorkspaceContextMenuOwnsAttention(page: Page): Promise<void> {
+  await expect(page.getByTestId("workspace-hover-card")).toHaveCount(0);
+}
+
+export async function expectWorkspaceRowHoverCleared(
+  page: Page,
+  workspaceId: string,
+): Promise<void> {
+  const workspaceKey = `${getServerId()}:${workspaceId}`;
+  await expect(page.getByTestId(`sidebar-workspace-kebab-${workspaceKey}`)).toBeHidden();
+  await expect(page.getByTestId("workspace-hover-card")).toHaveCount(0);
+}
+
+export async function expectWorkspaceContextMenuActions(
+  page: Page,
+  workspaceId: string,
+): Promise<void> {
+  const workspaceKey = `${getServerId()}:${workspaceId}`;
+  const menu = page.getByTestId(`sidebar-workspace-context-menu-${workspaceKey}`);
+  await expect(menu.getByRole("button", { name: "Copy path" })).toBeVisible();
+  await expect(menu.getByRole("button", { name: "Rename workspace" })).toBeVisible();
+  await expect(menu.getByRole("button", { name: "Archive" })).toBeVisible();
+}
+
+export async function openProjectContextMenu(page: Page, projectViewKey: string): Promise<void> {
+  const menuTestID = `sidebar-project-context-menu-${projectViewKey}`;
+  const anchor = await openContextMenuAtRowPoint(
+    page,
+    `sidebar-project-row-${projectViewKey}`,
+    menuTestID,
+  );
+  await expectContextMenuAtPointer(page, menuTestID, anchor);
+}
+
+export async function closeProjectContextMenu(page: Page, projectViewKey: string): Promise<void> {
+  await page.getByTestId(`sidebar-project-context-menu-${projectViewKey}-backdrop`).click();
+}
+
+export async function expectProjectContextMenuActions(
+  page: Page,
+  projectViewKey: string,
+): Promise<void> {
+  const menu = page.getByTestId(`sidebar-project-context-menu-${projectViewKey}`);
+  await expect(menu.getByRole("button", { name: "Open project settings" })).toBeVisible();
+  await expect(menu.getByRole("button", { name: "Remove project" })).toBeVisible();
+}
+
 export async function selectWorkspaceInSidebar(page: Page, workspaceId: string): Promise<void> {
  const row = page.getByTestId(`sidebar-workspace-row-${getServerId()}:${workspaceId}`);
  await expect(row).toBeVisible({ timeout: 30_000 });