@cueloop/client 0.1.0-alpha.20 → 0.1.0-alpha.22

package/src/App.tsx

@@ -11,28 +11,43 @@
 
 import React, { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
-import type { Clock } from "@opentui/core";
-import { isAgentNote, type ReviewSession, type VerdictKind } from "@cueloop/schema";
-import { displayText, marksByDisplay, spanKey, startSpan, type Mark, type SpanState } from "./view-plan";
+import type { Clock, MouseEvent } from "@opentui/core";
+import { type VerdictKind } from "@cueloop/schema";
+import { displayText, marksByDisplay, type Mark } from "./view-plan";
 import { noteForFile, viewedCount } from "./walk";
 import { DARK, dimmedTheme } from "./theme";
 import { DEFAULT_KEYS, loadConfig } from "./config";
 import { returnPaneFor } from "@cueloop/schema";
 import { createReviewController } from "./session-controller";
-import { reduceKey, type Intent, type KeyState } from "./keymap";
+import type { SessionClient } from "@cueloop/daemon/client";
+import { createIntentDispatch, reviewerAnnotations, type Mode } from "./intent-dispatch";
+import { reduceKey, type KeyState } from "./keymap";
 import { KeyBindings, type HintMode } from "./key-bindings";
 import { ThemeProvider } from "./components/theme-context";
 import { StatusBar } from "./components/primitives/StatusBar";
 import { Breadcrumb, type BreadcrumbItem } from "./components/Breadcrumb";
 import { PlanSheet, type PlanSheetHandle } from "./components/PlanSheet";
 import { DiffSheet } from "./components/DiffSheet";
-import { ReviewRail, annotationBlocking, type ReviewRailHandle } from "./components/ReviewRail";
-import { VERDICTS } from "./components/ConfirmCard";
+import { annotationBlocking, type ReviewRailHandle } from "./components/ReviewRail";
+import { ReviewPanel } from "./components/ReviewPanel";
+import {
+  REVIEW_DEFAULT_WIDTH,
+  resolveReviewWidth,
+  toggleReviewPanelMode,
+  widthFromMouseColumn,
+  type ReviewPanelMode,
+} from "./review-panel";
 import { CompletionOverlay } from "./components/CompletionOverlay";
 import { InboxList } from "./components/InboxList";
 import { ComposeBar } from "./components/ComposeBar";
 import { WalkWizard } from "./components/WalkWizard";
 
+/**
+ * The breadcrumb header and the status bar each occupy one terminal row; the
+ * review layout (plan column, divider, rail) gets the rows that remain.
+ */
+const CHROME_ROWS = 2;
+
 export interface AppProps {
   home?: string;
   sessionId?: string;
@@ -44,27 +59,26 @@ export interface AppProps {
   onExit?: (code: number) => void;
   /** Timer source for the auto-close countdown; tests inject a ManualClock. */
   clock?: Clock;
+  /** Session source; the sharing gateway injects a blob-backed client. */
+  openClient?: () => Promise<SessionClient>;
+  /**
+   * Who is at the keyboard. `owner` is the local planner (default). `observer`
+   * is a passive `cueloop serve` watcher (read-only). `collaborator` is a share
+   * viewer: annotates, but cannot edit the plan or submit an agent verdict.
+   */
+  role?: "owner" | "observer" | "collaborator";
 }
 
-type Mode =
-  | { type: "normal" }
-  | { type: "span"; span: SpanState }
-  | { type: "compose"; kind: "comment" | "suggestion"; displayIndex: number; start: number; end: number; text: string }
-  | { type: "railEdit"; id: string; text: string }
-  | { type: "submit"; verdict: VerdictKind; summary: string };
-
-/** Reviewer-authored annotations only: agent notes never count as feedback. */
-function reviewerAnnotations(session: ReviewSession) {
-  return session.annotations.filter((annotation) => !isAgentNote(annotation));
-}
-
-function defaultVerdict(session: ReviewSession): VerdictKind {
-  return reviewerAnnotations(session).length || session.workingCopy !== undefined ? "request_changes" : "approve";
-}
-
-export function App({ home, sessionId, readOnly = false, onExit, clock }: AppProps): React.ReactNode {
+export function App({ home, sessionId, readOnly = false, onExit, clock, openClient, role = "owner" }: AppProps): React.ReactNode {
+  // Observer stays fully read-only; a collaborator writes annotations but not
+  // the plan or a verdict. `observer` is what the controller and every write
+  // gate key off; the two capability flags carve out the collaborator's middle.
+  const observer = readOnly || role === "observer";
+  const canEditPlan = !observer && role !== "collaborator";
+  const canSubmitVerdict = !observer && role !== "collaborator";
+  const canShare = !observer && role === "owner";
   const controller = useMemo(
-    () => createReviewController({ home, sessionId, readOnly, onExit, clock }),
+    () => createReviewController({ home, sessionId, readOnly: observer, onExit, clock, openClient }),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [home, sessionId],
   );
@@ -78,7 +92,7 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
     controller.getSnapshot,
   );
   const renderer = useRenderer();
-  const { width: terminalWidth } = useTerminalDimensions();
+  const { width: terminalWidth, height: terminalHeight } = useTerminalDimensions();
 
   // ── view state ──────────────────────────────
   const [cursor, setCursor] = useState(0);
@@ -86,6 +100,13 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
   const [mode, setMode] = useState<Mode>({ type: "normal" });
   const [focusedAnnotationId, setFocusedAnnotationId] = useState<string | undefined>(undefined);
   const [railTab, setRailTab] = useState<"review" | "agent">("review");
+  // review panel layout: mode + expanded width are client view state, loaded
+  // from and persisted to the user config so they survive a restart. The ref
+  // mirrors the width so the drag-end persist reads the latest value.
+  const [reviewMode, setReviewMode] = useState<ReviewPanelMode>("expanded");
+  const [reviewWidth, setReviewWidth] = useState(REVIEW_DEFAULT_WIDTH);
+  const [dividerDragging, setDividerDragging] = useState(false);
+  const reviewWidthRef = useRef(REVIEW_DEFAULT_WIDTH);
   // ~2s focus pulse on the document highlight when a rail card is activated
   const [pulsedAnnotationId, setPulsedAnnotationId] = useState<string | null>(null);
   const pulseTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -103,6 +124,9 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
     keysRef.current = config.keys;
     keyBindings.setKeys(config.keys);
     setTheme(config.theme);
+    setReviewMode(config.ui.reviewState);
+    setReviewWidth(config.ui.reviewWidth);
+    reviewWidthRef.current = config.ui.reviewWidth;
     controller.applyConfig(config);
   }, [session?.workspace.repoRoot, controller, keyBindings]);
   useEffect(
@@ -172,7 +196,7 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
   };
 
   const openCardEdit = (annotationId: string): void => {
-    if (readOnly) return controller.setStatus("observer - read-only");
+    if (observer) return controller.setStatus("observer - read-only");
     if (resolved) return controller.setStatus("review submitted - read-only");
     const annotation = session?.annotations.find((candidate) => candidate.id === annotationId);
     if (!annotation) return;
@@ -191,143 +215,36 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
   };
 
   // ── keyboard grammar: build state, reduce, dispatch ──
-  const dispatch = (intent: Intent): void => {
-    switch (intent.type) {
-      case "exit":
-        return void onExit?.(0);
-      case "status":
-        return controller.setStatus(intent.message);
-      case "move": {
-        const navigableCount = isDiff ? rows.length : display.length;
-        if (intent.to === "down") setCursor((current) => Math.min(navigableCount - 1, current + 1));
-        else if (intent.to === "up") setCursor((current) => Math.max(0, current - 1));
-        else if (intent.to === "top") setCursor(0);
-        else setCursor(navigableCount - 1);
-        return;
-      }
-      case "inboxMove": {
-        const navigableCount = inbox?.length ?? 0;
-        setInboxCursor((current) => (intent.to === "down" ? Math.min(navigableCount - 1, current + 1) : Math.max(0, current - 1)));
-        return;
-      }
-      case "openSession": {
-        const selected = inbox?.[inboxCursor];
-        if (selected) controller.open(selected.id);
-        return;
-      }
-      case "startSpan": {
-        const block = display[cursor];
-        if (!block?.work) return;
-        const span = startSpan(cursor, displayText(block));
-        if (span) setMode({ type: "span", span });
-        return;
-      }
-      case "spanKey":
-        if (mode.type === "span") {
-          const span = spanKey(mode.span, intent.name, displayText(display[mode.span.displayIndex]!));
-          setMode({ type: "span", span });
-        }
-        return;
-      case "openCompose": {
-        liveInput.current = "";
-        if (intent.from === "span" && mode.type === "span") {
-          setMode({
-            type: "compose",
-            kind: intent.kind,
-            displayIndex: mode.span.displayIndex,
-            start: mode.span.start,
-            end: mode.span.end,
-            text: "",
-          });
-        } else if (isDiff) {
-          const row = rows[cursor];
-          if (row) setMode({ type: "compose", kind: intent.kind, displayIndex: cursor, start: 0, end: row.text.length, text: "" });
-        } else {
-          // a mouse drag leaves a native selection; it wins over the cursor block
-          const native = planSheetRef.current?.readSelection() ?? null;
-          if (native) {
-            setMode({ type: "compose", kind: intent.kind, ...native, text: "" });
-          } else {
-            const block = display[cursor];
-            if (block) setMode({ type: "compose", kind: intent.kind, displayIndex: cursor, start: 0, end: displayText(block).length, text: "" });
-          }
-        }
-        return;
-      }
-      case "openSubmit":
-        if (!session) return;
-        liveInput.current = "";
-        // the confirm card lives in the review tab; opening submit reveals it
-        setRailTab("review");
-        return void setMode({ type: "submit", verdict: defaultVerdict(session), summary: "" });
-      case "cut":
-        return controller.cut(cursor);
-      case "edit":
-        return runEditorHandOff();
-      case "editCard":
-        if (focusedAnnotationId) openCardEdit(focusedAnnotationId);
-        return;
-      case "nextAnnotation":
-      case "prevAnnotation": {
-        const annotations = session?.annotations ?? [];
-        if (!annotations.length) return;
-        const focusedIndex = annotations.findIndex((annotation) => annotation.id === focusedAnnotationId);
-        const nextIndex =
-          focusedIndex === -1
-            ? 0
-            : (focusedIndex + (intent.type === "nextAnnotation" ? 1 : -1) + annotations.length) % annotations.length;
-        return void selectCardFromDocument(annotations[nextIndex]!.id);
-      }
-      case "walkStart":
-        return controller.walkStart();
-      case "walkForward":
-        return controller.walkForward();
-      case "walkBack":
-        return controller.walkBack();
-      case "walkLeave":
-        return controller.walkLeave();
-      case "removeAnnotation":
-        if (focusedAnnotationId) {
-          controller.removeAnnotation(focusedAnnotationId);
-          setFocusedAnnotationId(undefined);
-        }
-        return;
-      case "deselect":
-        planSheetRef.current?.clearSelection();
-        setFocusedAnnotationId(undefined);
-        setPulsedAnnotationId(null);
-        return;
-      case "closeOverlay":
-        return void setMode({ type: "normal" });
-      case "saveCompose": {
-        const body = liveInput.current.trim();
-        if (mode.type === "railEdit") {
-          if (session && body) controller.updateAnnotation(mode.id, body);
-          return void setMode({ type: "normal" });
-        }
-        if (mode.type !== "compose") return;
-        if (session && body) {
-          const annotationId = controller.annotate(mode.kind, mode.displayIndex, mode.start, mode.end, body);
-          if (annotationId) setFocusedAnnotationId(annotationId);
-        }
-        return void setMode({ type: "normal" });
-      }
-      case "submitVerdict":
-        if (mode.type === "submit") controller.submit(mode.verdict, liveInput.current);
-        return void setMode({ type: "normal" });
-      case "cycleVerdict": {
-        if (mode.type !== "submit") return;
-        const verdictIndex = (VERDICTS.indexOf(mode.verdict) + intent.dir + VERDICTS.length) % VERDICTS.length;
-        return void setMode({ ...mode, verdict: VERDICTS[verdictIndex]! });
-      }
-      case "finishReview":
-        return controller.finishReview();
-      case "optInAutoClose":
-        return controller.optInAutoClose();
-      case "dismissCompletion":
-        return controller.dismissCompletion();
-    }
-  };
+  const dispatch = createIntentDispatch({
+    controller,
+    onExit,
+    isDiff,
+    display,
+    rows,
+    cursor,
+    inbox,
+    inboxCursor,
+    mode,
+    session,
+    reviewMode,
+    reviewWidth,
+    terminalWidth,
+    focusedAnnotationId,
+    liveInput,
+    reviewWidthRef,
+    planSheetRef,
+    setCursor,
+    setInboxCursor,
+    setMode,
+    setReviewMode,
+    setReviewWidth,
+    setRailTab,
+    setFocusedAnnotationId,
+    setPulsedAnnotationId,
+    selectCardFromDocument,
+    runEditorHandOff,
+    openCardEdit,
+  });
 
   const overlay: KeyState["overlay"] =
     mode.type === "compose" || mode.type === "railEdit"
@@ -345,7 +262,10 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
   useKeyboard((key) => {
     const state: KeyState = {
       keys: keysRef.current,
-      readOnly,
+      readOnly: observer,
+      canEditPlan,
+      canSubmitVerdict,
+      canShare,
       overlay,
       view: !session ? "inbox" : isDiff ? "diff" : "plan",
       spanMode: mode.type === "span",
@@ -360,7 +280,8 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
     };
     keyBindings.setContext({ overlay: state.overlay, spanMode: state.spanMode });
     const action = keyBindings.resolveAction({ name: key.name, shift: !!key.shift });
-    for (const intent of reduceKey(state, { name: key.name, shift: !!key.shift }, action)) dispatch(intent);
+    for (const intent of reduceKey(state, { name: key.name, shift: !!key.shift, meta: !!key.meta }, action))
+      dispatch(intent);
   });
 
   // ── render ──────────────────────────────────
@@ -437,18 +358,38 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
   };
 
   const onEditRequest = (): void => {
-    if (readOnly) return controller.setStatus("observer - read-only");
+    if (observer) return controller.setStatus("observer - read-only");
+    if (!canEditPlan) return controller.setStatus("shared plan - edit it in your own copy");
     if (resolved) return controller.setStatus("review submitted - read-only");
     runEditorHandOff();
   };
 
+  // clicking the rail Share button: publish the plan, copy the ssh line
+  const onShareRequest = (): void => {
+    if (!canShare) return controller.setStatus("only the plan owner can share");
+    controller.share();
+  };
+
   // clicking the rail Submit button: same read-only answer as the submit key
   const onSubmitRequest = (): void => {
-    if (readOnly) return controller.setStatus("observer - read-only");
+    if (observer) return controller.setStatus("observer - read-only");
+    if (!canSubmitVerdict) return controller.setStatus("shared view - your notes save as you go");
     if (resolved) return;
     dispatch({ type: "openSubmit" });
   };
 
+  // the clickable chevron toggles expanded <-> compact; the keybinding (b)
+  // cycles all three including hidden
+  const onToggleReviewPanel = (): void => {
+    const next = toggleReviewPanelMode(reviewMode);
+    setReviewMode(next);
+    controller.saveReviewPanel({ mode: next });
+  };
+  // grabbing the divider only arms a drag when there is a width to drag
+  const onDividerGrab = (): void => {
+    if (reviewMode === "expanded") setDividerDragging(true);
+  };
+
   const submitConfirmState =
     mode.type === "submit"
       ? {
@@ -489,12 +430,13 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
     { label: "cueloop", tone: "accent" },
     { label: `${activeSession.artifact.meta.title ?? activeSession.artifact.meta.planPath ?? activeSession.id} · rev ${activeSession.revisions.length}`, tone: "dim" },
     ...(resolved ? [{ label: `resolved: ${activeSession.verdict!.kind.replace("_", " ")}`, tone: "green" as const }] : []),
-    ...(readOnly ? [{ label: "observer", tone: "dim" as const }] : []),
+    ...(observer ? [{ label: "observer", tone: "dim" as const }] : []),
+    ...(role === "collaborator" ? [{ label: "shared · your notes save as you go", tone: "dim" as const }] : []),
     ...(status ? [{ label: status, tone: "accent" as const }] : []),
   ];
 
   keyBindings.setContext({ overlay, spanMode: mode.type === "span" });
-  const hintMode: HintMode = readOnly
+  const hintMode: HintMode = observer
     ? "read-only"
     : mode.type === "submit"
       ? "submit"
@@ -507,11 +449,23 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
             : focusedAnnotationId !== undefined
               ? "card"
               : "normal";
-  const railWidth = terminalWidth >= 100 ? 34 : 28;
 
   return (
     <ThemeProvider theme={theme}>
-      <box style={{ flexDirection: "column", width: "100%", height: "100%", backgroundColor: theme.bg }}>
+      <box
+        style={{ flexDirection: "column", width: "100%", height: "100%", backgroundColor: theme.bg }}
+        onMouseDrag={(event: MouseEvent) => {
+          if (!dividerDragging || reviewMode !== "expanded") return;
+          const next = widthFromMouseColumn(event.x, terminalWidth);
+          reviewWidthRef.current = next;
+          setReviewWidth(next);
+        }}
+        onMouseUp={() => {
+          if (!dividerDragging) return;
+          setDividerDragging(false);
+          controller.saveReviewPanel({ width: reviewWidthRef.current });
+        }}
+      >
         <Breadcrumb items={headerItems} />
         <box style={{ flexGrow: 1, flexDirection: "row" }}>
           {isDiff ? (
@@ -537,20 +491,28 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
               onEditRequest={onEditRequest}
             />
           )}
-          <ReviewRail
-            ref={railRef}
-            session={activeSession}
-            selectedId={focusedAnnotationId}
-            resolvedIds={isDiff ? null : resolvedIds}
-            railTab={railTab}
-            pendingCount={pendingCount}
-            cardEdit={cardEditState}
-            submitConfirm={submitConfirmState}
-            onTabChange={setRailTab}
-            onSelectCard={selectCardFromRail}
-            onActivateCard={openCardEdit}
-            onSubmitRequest={onSubmitRequest}
-            width={railWidth}
+          <ReviewPanel
+            mode={reviewMode}
+            width={resolveReviewWidth(reviewWidth, terminalWidth)}
+            height={terminalHeight - CHROME_ROWS}
+            dragging={dividerDragging}
+            onDividerGrab={onDividerGrab}
+            onToggle={onToggleReviewPanel}
+            railRef={railRef}
+            rail={{
+              session: activeSession,
+              selectedId: focusedAnnotationId,
+              resolvedIds: isDiff ? null : resolvedIds,
+              railTab,
+              pendingCount,
+              cardEdit: cardEditState,
+              submitConfirm: submitConfirmState,
+              onTabChange: setRailTab,
+              onSelectCard: selectCardFromRail,
+              onActivateCard: openCardEdit,
+              onSubmitRequest,
+              onShareRequest: canShare ? onShareRequest : undefined,
+            }}
           />
         </box>
         {mode.type === "compose" && isDiff ? (

package/src/App.walk.test.tsx

@@ -1,11 +1,4 @@
-/**
- * The guided walk in the virtual terminal: the wizard steps every
- * changed file with a plain progress title, ] marks viewed and persists with
- * the session, esc keeps progress, w resumes at the first unviewed file
- * (across App instances - the daemon round-trip), the agent-note block
- * renders only for files carrying a note, and the end card hands over to the
- * submit confirm with the honest viewed count.
- */
+/** The guided walk in the virtual terminal: the wizard steps every changed file with a plain progress title, ] marks viewed and persists with the session, esc keeps progress, w resumes at the first unviewed file (across App instances via the daemon round-trip), the agent-note block renders only for files carrying a note, and the end card hands over to the submit confirm with the honest viewed count. */
 
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
@@ -87,56 +80,93 @@ function foregroundsOf(setup: Setup, needle: string): string[] {
 
 describe("the guided walk", () => {
   test("w walks all three files: progress title, persisted marks, end card, submit hand-over", async () => {
+    // Arrange
     const setup = await renderApp();
+
+    // Act
     await press(setup, "w");
+
+    // Assert
     await waitForText(setup, "file 1 of 3 · 0 viewed");
     expect(setup.captureCharFrame()).toContain("src/a.ts");
     expect(setup.captureCharFrame()).toContain("+1 -1");
 
+    // Act
     await press(setup, "]");
+
+    // Assert
     await waitForText(setup, "file 2 of 3 · 1 viewed");
     // the viewed mark rides the session record, not the client
     await waitForState(setup, () => (server.core.sessionGet(session.id).viewedPaths ?? []).includes("src/a.ts"));
 
+    // Act
     // [ steps back; the revisited card shows its viewed marker
     await press(setup, "[");
+
+    // Assert
     await waitForText(setup, "file 1 of 3 · 1 viewed");
     expect(setup.captureCharFrame()).toContain("· viewed");
+
+    // Act
     await press(setup, "]");
+
+    // Assert
     await waitForText(setup, "file 2 of 3 · 1 viewed");
 
+    // Act
     await press(setup, "]");
+
+    // Assert
     await waitForText(setup, "file 3 of 3 · 2 viewed");
+
+    // Act
     await press(setup, "]");
+
+    // Assert
     await waitForText(setup, "walk complete");
     expect(setup.captureCharFrame()).toContain("every file viewed (3/3)");
     expect(server.core.sessionGet(session.id).viewedPaths).toEqual(["src/a.ts", "src/b.ts", "src/c.ts"]);
 
+    // Act
     // the end card's return leaves the walk and opens the rail confirm
     await press(setup, "enter");
+
+    // Assert
     await waitForText(setup, "submit review");
     expect(setup.captureCharFrame()).toContain("3/3 files viewed");
+
+    // Act
     await press(setup, "enter");
+
+    // Assert
     await waitForState(setup, () => server.core.sessionGet(session.id).status === "resolved");
   });
 
   test("esc keeps progress and w resumes at the first unviewed file", async () => {
+    // Arrange
     const setup = await renderApp();
     await press(setup, "w");
     await waitForText(setup, "file 1 of 3 · 0 viewed");
     await press(setup, "]");
     await waitForText(setup, "file 2 of 3 · 1 viewed");
 
+    // Act
     await press(setup, "escape");
+
+    // Assert
     await waitForTextGone(setup, "file 2 of 3");
     // the sheet is back at full strength: no wizard card on screen
     expect(setup.captureCharFrame()).not.toContain("· 1 viewed");
 
+    // Act
     await press(setup, "w");
+
+    // Assert
     await waitForText(setup, "file 2 of 3 · 1 viewed");
   });
 
   test("a half-walked review resumes across App instances via the daemon", async () => {
+    // Arrange
     const first = await renderApp();
     await press(first, "w");
     await waitForText(first, "file 1 of 3 · 0 viewed");
@@ -146,15 +176,19 @@ describe("the guided walk", () => {
     await waitForState(first, () => (server.core.sessionGet(session.id).viewedPaths ?? []).length === 2);
     first.renderer.destroy();
 
+    // Act
     // a fresh client reads the viewed set back from the session record
     const second = await renderApp();
     await press(second, "w");
+
+    // Assert
     await waitForText(second, "file 3 of 3 · 2 viewed");
     expect(second.captureCharFrame()).toContain("src/c.ts");
     // two full App boots with daemon round-trips need more than the default budget
   }, 15_000);
 
   test("the agent-note block renders only for files carrying a note", async () => {
+    // Arrange
     server.core.sessionAnnotate(session.id, {
       id: "note-b",
       kind: "note",
@@ -162,14 +196,22 @@ describe("the guided walk", () => {
       body: "Swaps the stale line for the new constant.",
     });
     const setup = await renderApp();
+
+    // Act
     await press(setup, "w");
+
+    // Assert
     await waitForText(setup, "file 1 of 3");
     expect(setup.captureCharFrame()).not.toContain("agent note");
 
+    // Act
     await press(setup, "]");
+
+    // Assert
     await waitForText(setup, "agent note");
     expect(setup.captureCharFrame()).toContain("Swaps the stale line for the new constant.");
 
+    // Act
     // a note is agent context, not reviewer feedback: it neither counts nor
     // flips the default verdict, and never comes back in the feedback doc
     await press(setup, "escape");
@@ -177,6 +219,8 @@ describe("the guided walk", () => {
     await press(setup, "enter");
     await waitForText(setup, "0 annotations");
     await press(setup, "enter");
+
+    // Assert
     await waitForState(setup, () => server.core.sessionGet(session.id).status === "resolved");
     const resolved = server.core.sessionGet(session.id);
     expect(resolved.verdict!.kind).toBe("approve");
@@ -184,12 +228,18 @@ describe("the guided walk", () => {
   });
 
   test("the sheet dims behind the wizard; the preview keeps the diff colors", async () => {
+    // Arrange
     const setup = await renderApp();
+
+    // Assert
     // before the walk the sheet's added line wears the insertion color
     await waitForText(setup, "+new line");
     expect(foregroundsOf(setup, "+new line")).toContain(DARK.insFg);
 
+    // Act
     await press(setup, "w");
+
+    // Assert
     await waitForText(setup, "file 1 of 3 · 0 viewed");
     // dimmed: the sheet line drops to the dim token...
     expect(foregroundsOf(setup, "+new line")).toEqual([DARK.textDim]);
@@ -198,10 +248,15 @@ describe("the guided walk", () => {
   });
 
   test("walking a resolved review answers read-only", async () => {
+    // Arrange
     server.core.sessionResolve(session.id, "approve", "");
     const setup = await renderApp();
     await waitForText(setup, "resolved");
+
+    // Act
     await press(setup, "w");
+
+    // Assert
     await waitForText(setup, "review submitted - read-only");
     expect(setup.captureCharFrame()).not.toContain("file 1 of 3");
   });

package/src/clipboard.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { clipboardCommands } from "./clipboard";
+
+describe(clipboardCommands, () => {
+  test("uses pbcopy on macOS", () => {
+    // Assert
+    expect(clipboardCommands("darwin")).toEqual([["pbcopy"]]);
+  });
+
+  test("uses clip.exe on Windows", () => {
+    // Assert
+    expect(clipboardCommands("win32")).toEqual([["clip.exe"]]);
+  });
+
+  test("prefers wayland, then X11 tools on Linux", () => {
+    // Act
+    const commands = clipboardCommands("linux");
+
+    // Assert
+    expect(commands[0]).toEqual(["wl-copy"]);
+    expect(commands.map((command) => command[0])).toEqual(["wl-copy", "xclip", "xsel"]);
+  });
+});