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

package/src/App.tsx

@@ -12,14 +12,16 @@
 import React, { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
 import type { Clock, MouseEvent } 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 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";
@@ -30,14 +32,11 @@ import { annotationBlocking, type ReviewRailHandle } from "./components/ReviewRa
 import { ReviewPanel } from "./components/ReviewPanel";
 import {
   REVIEW_DEFAULT_WIDTH,
-  REVIEW_RESIZE_STEP,
-  cycleReviewPanelMode,
   resolveReviewWidth,
   toggleReviewPanelMode,
   widthFromMouseColumn,
   type ReviewPanelMode,
 } from "./review-panel";
-import { VERDICTS } from "./components/ConfirmCard";
 import { CompletionOverlay } from "./components/CompletionOverlay";
 import { InboxList } from "./components/InboxList";
 import { ComposeBar } from "./components/ComposeBar";
@@ -60,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],
   );
@@ -198,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;
@@ -217,158 +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 expanded review rail; a compact or hidden
-        // panel would swallow the whole submit flow, so force the rail open (live
-        // only - the saved panel preference is left untouched)
-        setReviewMode("expanded");
-        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.direction + 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();
-      case "cycleReviewPanel": {
-        const next = cycleReviewPanelMode(reviewMode);
-        setReviewMode(next);
-        return controller.saveReviewPanel({ mode: next });
-      }
-      case "resizeReviewPanel": {
-        if (reviewMode !== "expanded") return;
-        const next = resolveReviewWidth(reviewWidth + intent.direction * REVIEW_RESIZE_STEP, terminalWidth);
-        reviewWidthRef.current = next;
-        setReviewWidth(next);
-        return controller.saveReviewPanel({ width: next });
-      }
-    }
-  };
+  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"
@@ -386,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",
@@ -479,14 +358,22 @@ 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" });
   };
@@ -543,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"
@@ -623,6 +511,7 @@ export function App({ home, sessionId, readOnly = false, onExit, clock }: AppPro
               onSelectCard: selectCardFromRail,
               onActivateCard: openCardEdit,
               onSubmitRequest,
+              onShareRequest: canShare ? onShareRequest : undefined,
             }}
           />
         </box>

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"]);
+  });
+});

package/src/clipboard.ts

@@ -0,0 +1,26 @@
+/**
+ * Best-effort system clipboard. Each platform has its own tool; we try them in
+ * order and report whether one worked, so the caller can fall back to printing
+ * the line (the over-SSH case, where no clipboard tool exists). Mirrors how
+ * herdr confirms a copy.
+ */
+
+/** The clipboard-write commands to try, most-preferred first, for this platform. */
+export function clipboardCommands(platform: NodeJS.Platform = process.platform): string[][] {
+  if (platform === "darwin") return [["pbcopy"]];
+  if (platform === "win32") return [["clip.exe"]];
+  return [["wl-copy"], ["xclip", "-selection", "clipboard"], ["xsel", "--clipboard", "--input"]];
+}
+
+/** Copy `text` to the clipboard; false when no tool is available or all fail. */
+export async function copyToClipboard(text: string): Promise<boolean> {
+  for (const command of clipboardCommands()) {
+    try {
+      const proc = Bun.spawn(command, { stdin: Buffer.from(text), stdout: "ignore", stderr: "ignore" });
+      if ((await proc.exited) === 0) return true;
+    } catch {
+      // tool not installed - try the next one
+    }
+  }
+  return false;
+}

package/src/components/ReviewRail.tsx

@@ -8,7 +8,7 @@
 
 import React, { forwardRef, useImperativeHandle, useRef } from "react";
 import type { ScrollBoxRenderable } from "@opentui/core";
-import type { Annotation, ReviewSession } from "@cueloop/schema";
+import { isAddressed, type Annotation, type ReviewSession } from "@cueloop/schema";
 import type { Theme } from "../theme";
 import { useComponentTheme } from "./theme-context";
 import { Tabs, Tab, TabList } from "./primitives/Tabs";
@@ -40,6 +40,8 @@ export interface ReviewRailProps {
   onSelectCard: (id: string) => void;
   onActivateCard: (id: string) => void;
   onSubmitRequest: () => void;
+  /** Publish the plan as a share; omitted for non-owners (hides the button). */
+  onShareRequest?: () => void;
   /** Rail column width; the app derives it from the persisted review layout. */
   width?: number;
   /**
@@ -68,6 +70,7 @@ export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function
     onSelectCard,
     onActivateCard,
     onSubmitRequest,
+    onShareRequest,
     width = 34,
     onCollapse,
     theme,
@@ -76,6 +79,9 @@ export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function
 ): React.ReactNode {
   const tokens = useComponentTheme(theme);
   const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+  // addressed annotations leave the card list; a dim count keeps them honest
+  const openAnnotations = session.annotations.filter((annotation) => !isAddressed(annotation));
+  const addressedCount = session.annotations.length - openAnnotations.length;
 
   useImperativeHandle(handleRef, () => ({
     revealCard: (annotationId: string): void => {
@@ -101,11 +107,12 @@ export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function
       ) : (
         <>
           {session.workingCopy !== undefined ? <text fg={tokens.textDim}>± plan edits → one diff</text> : null}
-          {session.annotations.length === 0 ? (
-            <text fg={tokens.textDim}>no annotations yet</text>
+          {addressedCount > 0 ? <text fg={tokens.textDim}>✓ {addressedCount} addressed by revision</text> : null}
+          {openAnnotations.length === 0 ? (
+            <text fg={tokens.textDim}>{session.annotations.length === 0 ? "no annotations yet" : "all annotations addressed"}</text>
           ) : (
             <scrollbox ref={scrollRef} style={{ flexGrow: 1 }} focused={false}>
-              {session.annotations.map((annotation) => (
+              {openAnnotations.map((annotation) => (
                 <AnnotationCard
                   key={annotation.id}
                   id={`annotation-card-${annotation.id}`}
@@ -145,6 +152,11 @@ export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function
               {`Submit review (${pendingCount}) ⏎`}
             </Button>
           )}
+          {onShareRequest && session.status !== "resolved" ? (
+            <Button variant="plain" onPress={onShareRequest} theme={theme}>
+              {"Share plan ⇧S"}
+            </Button>
+          ) : null}
         </>
       )}
       {/* the collapse chevron: muted, left-bound, one column from the divider.

package/src/components/stories.test.tsx

@@ -28,10 +28,15 @@ describe("stories catalog", () => {
 
   for (const { moduleTitle, storyName, story } of stories) {
     test(`${moduleTitle}/${storyName} renders, snapshots, and carries its colors`, async () => {
+      // Arrange
       const size = story.size ?? { width: 80, height: 24 };
+
+      // Act
       const setup = await testRender(story.render(), size);
       await setup.waitForVisualIdle();
       const frame = setup.captureCharFrame();
+
+      // Assert
       expect(frame).toMatchSnapshot(`${moduleTitle}/${storyName}`);
       if (story.expectedColors?.length) {
         const seenColors = new Set<string>();