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

package/src/intent-dispatch.ts

@@ -0,0 +1,270 @@
+/**
+ * The intent reducer: one effectful handler per keymap Intent, lifted out of
+ * the App component so the 30-case grammar can be read and tested on its own.
+ * keymap.ts turns keys into Intents (pure); this turns an Intent into the
+ * matching controller call or view-state update. App builds the dependency
+ * bag once per render and hands it here; nothing in this module reaches back
+ * into React beyond the setters it is given.
+ */
+
+import type { Dispatch, MutableRefObject, RefObject, SetStateAction } from "react";
+import { isAddressed, isAgentNote, type ReviewSession, type VerdictKind } from "@cueloop/schema";
+import { displayText, spanKey, startSpan, type DisplayBlock, type SpanState } from "./view-plan";
+import type { DiffRow } from "./view-diff";
+import type { ReviewController } from "./session-controller";
+import type { Intent } from "./keymap";
+import type { PlanSheetHandle } from "./components/PlanSheet";
+import { VERDICTS } from "./components/ConfirmCard";
+import { REVIEW_RESIZE_STEP, cycleReviewPanelMode, resolveReviewWidth, type ReviewPanelMode } from "./review-panel";
+
+/** The one overlay/mode the TUI is in; every compose/submit/edit flow is a variant. */
+export 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 };
+
+/**
+ * Annotations that still count as feedback: agent notes never do, and an
+ * annotation a revision already addressed is settled - it neither blocks the
+ * verdict default nor re-enters the next feedback document.
+ */
+export function reviewerAnnotations(session: ReviewSession) {
+  return session.annotations.filter((annotation) => !isAgentNote(annotation) && !isAddressed(annotation));
+}
+
+export function defaultVerdict(session: ReviewSession): VerdictKind {
+  return reviewerAnnotations(session).length || session.workingCopy !== undefined ? "request_changes" : "approve";
+}
+
+/**
+ * Everything the reducer reads or writes, supplied fresh each render: the
+ * controller and exit hook, the derived reads (view rows, cursor, mode,
+ * session), the refs it pokes, the state setters, and the three App-owned
+ * selection helpers it composes.
+ */
+export interface IntentDispatchDeps {
+  controller: ReviewController;
+  onExit?: (code: number) => void;
+
+  isDiff: boolean;
+  display: DisplayBlock[];
+  rows: DiffRow[];
+  cursor: number;
+  inbox: ReviewSession[] | null;
+  inboxCursor: number;
+  mode: Mode;
+  session: ReviewSession | null;
+  reviewMode: ReviewPanelMode;
+  reviewWidth: number;
+  terminalWidth: number;
+  focusedAnnotationId: string | undefined;
+
+  liveInput: MutableRefObject<string>;
+  reviewWidthRef: MutableRefObject<number>;
+  planSheetRef: RefObject<PlanSheetHandle | null>;
+
+  setCursor: Dispatch<SetStateAction<number>>;
+  setInboxCursor: Dispatch<SetStateAction<number>>;
+  setMode: Dispatch<SetStateAction<Mode>>;
+  setReviewMode: Dispatch<SetStateAction<ReviewPanelMode>>;
+  setReviewWidth: Dispatch<SetStateAction<number>>;
+  setRailTab: Dispatch<SetStateAction<"review" | "agent">>;
+  setFocusedAnnotationId: Dispatch<SetStateAction<string | undefined>>;
+  setPulsedAnnotationId: Dispatch<SetStateAction<string | null>>;
+
+  selectCardFromDocument: (annotationId: string) => void;
+  runEditorHandOff: () => void;
+  openCardEdit: (annotationId: string) => void;
+}
+
+/** Build the intent handler for one render from its dependency bag. */
+export function createIntentDispatch(deps: IntentDispatchDeps): (intent: Intent) => void {
+  const {
+    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,
+  } = deps;
+
+  return (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 "share":
+        return controller.share();
+      case "cut":
+        return controller.cut(cursor);
+      case "edit":
+        return runEditorHandOff();
+      case "editCard":
+        if (focusedAnnotationId) openCardEdit(focusedAnnotationId);
+        return;
+      case "nextAnnotation":
+      case "prevAnnotation": {
+        // cycle open cards only - addressed ones are out of the rail
+        const annotations = (session?.annotations ?? []).filter((annotation) => !isAddressed(annotation));
+        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 });
+      }
+    }
+  };
+}

package/src/key-bindings.test.ts

@@ -1,8 +1,4 @@
-/**
- * Binding resolution and hint generation over @opentui/keymap: config keys
- * resolve to action names per layer, and the status-line hints derive from
- * getActiveKeys() so rebinds surface in the hint text.
- */
+/** Config keys resolve to per-layer actions, and status hints derive from getActiveKeys() so rebinds surface. */
 
 import { describe, expect, test } from "bun:test";
 import { DEFAULT_KEYS } from "./config";
@@ -43,28 +39,40 @@ describe("grammar-layer resolution", () => {
 
 describe("mode layers own their keys", () => {
   test("span mode resolves the span verbs, not the grammar", () => {
+    // Arrange
     const resolver = bindings({ spanMode: true });
+
+    // Assert
     expect(resolver.resolveAction({ name: "l", shift: false })).toBe("span_grow");
     expect(resolver.resolveAction({ name: "c", shift: false })).toBe("span_comment");
     expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("span_cancel");
   });
 
   test("the compose overlay only knows save and cancel", () => {
+    // Arrange
     const resolver = bindings({ overlay: "compose" });
+
+    // Assert
     expect(resolver.resolveAction({ name: "return", shift: false })).toBe("save_compose");
     expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("cancel_overlay");
     expect(resolver.resolveAction({ name: "j", shift: false })).toBeUndefined();
   });
 
   test("the submit overlay adds the verdict arrows", () => {
+    // Arrange
     const resolver = bindings({ overlay: "submit" });
+
+    // Assert
     expect(resolver.resolveAction({ name: "left", shift: false })).toBe("cycle_verdict_left");
     expect(resolver.resolveAction({ name: "right", shift: false })).toBe("cycle_verdict_right");
     expect(resolver.resolveAction({ name: "return", shift: false })).toBe("submit_verdict");
   });
 
   test("the walk overlay owns the bracket stepping and leaves the grammar keys dead", () => {
+    // Arrange
     const resolver = bindings({ overlay: "walk" });
+
+    // Assert
     expect(resolver.resolveAction({ name: "]", shift: false })).toBe("walk_next");
     expect(resolver.resolveAction({ name: "[", shift: false })).toBe("walk_prev");
     expect(resolver.resolveAction({ name: "escape", shift: false })).toBe("walk_leave");
@@ -111,8 +119,11 @@ describe("getActiveKeys-generated status hints", () => {
   });
 
   test("a rebound key shows its real binding in the hint", () => {
+    // Arrange
     const resolver = new KeyBindings({ ...DEFAULT_KEYS, comment: ["m"] });
     resolver.setContext({ overlay: "none", spanMode: false });
+
+    // Assert
     expect(resolver.resolveAction({ name: "m", shift: false })).toBe("comment");
     expect(resolver.resolveAction({ name: "c", shift: false })).toBeUndefined();
     expect(resolver.statusHint("normal")).toContain("m comment");

package/src/keymap.test.ts

@@ -1,8 +1,4 @@
-/**
- * The keyboard grammar as data: every mode x key produces a known intent
- * list, the read-only rule is one gate, and plan and diff reviews share one
- * path for annotation navigation, deletion, and submit.
- */
+/** The keyboard grammar as data: every mode x key maps to a known intent list, gated once by the read-only rule. */
 
 import { describe, expect, test } from "bun:test";
 import { DEFAULT_KEYS } from "./config";
@@ -30,6 +26,7 @@ function key(name: string, shift = false, meta = false): { name: string; shift:
 }
 
 describe("compose overlay", () => {
+  // Arrange
   const keyState = state({ overlay: "compose" });
   const table: [string, Intent[]][] = [
     ["escape", [{ type: "closeOverlay" }]],
@@ -57,6 +54,7 @@ describe("compose overlay", () => {
 });
 
 describe("submit overlay", () => {
+  // Arrange
   const keyState = state({ overlay: "submit" });
   const table: [string, Intent[]][] = [
     ["escape", [{ type: "closeOverlay" }]],
@@ -75,6 +73,7 @@ describe("submit overlay", () => {
 });
 
 describe("completion overlay", () => {
+  // Arrange
   const prompt = state({ overlay: "completion-prompt" });
   const counting = state({ overlay: "completion-counting" });
   const table: [KeyState, string, Intent[]][] = [
@@ -97,6 +96,7 @@ describe("completion overlay", () => {
 });
 
 describe("inbox mode", () => {
+  // Arrange
   const keyState = state({ view: "inbox" });
   const table: [string, Intent[]][] = [
     ["j", [{ type: "inboxMove", to: "down" }]],
@@ -116,7 +116,10 @@ describe("inbox mode", () => {
   }
 
   test("an empty inbox swallows every non-quit key", () => {
+    // Arrange
     const empty = state({ view: "inbox", hasInboxItems: false });
+
+    // Assert
     for (const name of ["j", "k", "down", "up", "return", "enter"]) {
       expect(reduceKey(empty, key(name))).toEqual([]);
     }
@@ -124,7 +127,63 @@ describe("inbox mode", () => {
   });
 });
 
+describe("collaborator (share) capabilities", () => {
+  test("can annotate: comment opens the composer", () => {
+    // Arrange
+    const collab = state({ canEditPlan: false, canSubmitVerdict: false });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("c"), "comment")).toEqual([{ type: "openCompose", kind: "comment", from: "cursor" }]);
+  });
+
+  test("can edit their own card: edit with a focused annotation rewrites it", () => {
+    // Arrange
+    const collab = state({ canEditPlan: false, hasFocusedAnnotation: true });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("e"), "edit")).toEqual([{ type: "editCard" }]);
+  });
+
+  test("cannot edit the plan: cut/edit with no card is refused", () => {
+    // Arrange
+    const collab = state({ canEditPlan: false, hasFocusedAnnotation: false });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("e"), "edit")).toEqual([{ type: "status", message: "shared plan - edit it in your own copy" }]);
+    expect(reduceKey(collab, key("c"), "cut")).toEqual([{ type: "status", message: "shared plan - edit it in your own copy" }]);
+  });
+
+  test("cannot submit a verdict: there is no agent on a share", () => {
+    // Arrange
+    const collab = state({ canSubmitVerdict: false });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("x"), "submit")).toEqual([{ type: "status", message: "shared view - your notes save as you go; q to leave" }]);
+  });
+
+  test("cannot re-share: only the owner shares", () => {
+    // Arrange
+    const collab = state({ canShare: false });
+
+    // Act / Assert
+    expect(reduceKey(collab, key("S", true), "share")).toEqual([{ type: "status", message: "only the plan owner can share" }]);
+  });
+});
+
+describe("share", () => {
+  test("the owner's share key publishes", () => {
+    // Act / Assert
+    expect(reduceKey(state(), key("S", true), "share")).toEqual([{ type: "share" }]);
+  });
+
+  test("an observer cannot share", () => {
+    // Act / Assert
+    expect(reduceKey(state({ readOnly: true }), key("S", true), "share")).toEqual([{ type: "status", message: "observer - read-only" }]);
+  });
+});
+
 describe("plan normal mode", () => {
+  // Arrange
   const keyState = state();
   const table: [string, boolean, Intent[]][] = [
     ["j", false, [{ type: "move", to: "down" }]],
@@ -154,7 +213,10 @@ describe("plan normal mode", () => {
   }
 
   test("resolved sessions guard the mutating verbs", () => {
+    // Arrange
     const resolvedState = state({ resolved: true });
+
+    // Assert
     for (const name of ["c", "s", "x", "e"]) {
       expect(reduceKey(resolvedState, key(name))).toEqual([{ type: "status", message: "review submitted - read-only" }]);
     }
@@ -163,27 +225,37 @@ describe("plan normal mode", () => {
   });
 
   test("cut text cannot host a comment or a span", () => {
+    // Arrange
     const cut = state({ cursorAnnotatable: false });
+
+    // Assert
     expect(reduceKey(cut, key("c"))).toEqual([{ type: "status", message: "text is cut - restore it first" }]);
     expect(reduceKey(cut, key("s"))).toEqual([{ type: "status", message: "text is cut - restore it first" }]);
     expect(reduceKey(cut, key("v"))).toEqual([]);
   });
 
   test("annotation navigation without annotations reports, delete without focus is silent", () => {
+    // Arrange
     const none = state({ annotationCount: 0, hasFocusedAnnotation: false });
+
+    // Assert
     expect(reduceKey(none, key("n"))).toEqual([{ type: "status", message: "no annotations" }]);
     expect(reduceKey(none, key("p"))).toEqual([{ type: "status", message: "no annotations" }]);
     expect(reduceKey(none, key("backspace"))).toEqual([]);
   });
 
   test("without a selected card x cuts the block and e opens the editor", () => {
+    // Arrange
     const unfocused = state({ hasFocusedAnnotation: false });
+
+    // Assert
     expect(reduceKey(unfocused, key("x"))).toEqual([{ type: "cut" }]);
     expect(reduceKey(unfocused, key("e"))).toEqual([{ type: "edit" }]);
   });
 });
 
 describe("span mode", () => {
+  // Arrange
   const keyState = state({ spanMode: true });
   const table: [string, Intent[]][] = [
     ["l", [{ type: "spanKey", name: "l" }]],
@@ -206,6 +278,7 @@ describe("span mode", () => {
 });
 
 describe("diff mode", () => {
+  // Arrange
   const keyState = state({ view: "diff" });
   const table: [string, Intent[]][] = [
     ["j", [{ type: "move", to: "down" }]],
@@ -229,6 +302,7 @@ describe("diff mode", () => {
   }
 
   test("comment guards: resolved first, then non-code rows", () => {
+    // Assert
     expect(reduceKey(state({ view: "diff", resolved: true }), key("c"))).toEqual([
       { type: "status", message: "review submitted - read-only" },
     ]);
@@ -240,6 +314,7 @@ describe("diff mode", () => {
 
 describe("guided walk", () => {
   test("w enters the walk in diff view; resolved and read-only sessions answer", () => {
+    // Assert
     expect(reduceKey(state({ view: "diff" }), key("w"))).toEqual([{ type: "walkStart" }]);
     expect(reduceKey(state({ view: "diff", resolved: true }), key("w"))).toEqual([
       { type: "status", message: "review submitted - read-only" },
@@ -250,6 +325,7 @@ describe("guided walk", () => {
     expect(reduceKey(state(), key("w"))).toEqual([{ type: "status", message: "the guided walk is a diff-review mode" }]);
   });
 
+  // Arrange
   const walking = state({ view: "diff", overlay: "walk" });
   const table: [string, Intent[]][] = [
     ["]", [{ type: "walkForward" }]],
@@ -268,7 +344,10 @@ describe("guided walk", () => {
   }
 
   test("the end card's return leaves the walk and opens the submit confirm", () => {
+    // Arrange
     const atEnd = state({ view: "diff", overlay: "walk", walkAtEnd: true });
+
+    // Assert
     expect(reduceKey(atEnd, key("return"))).toEqual([{ type: "walkLeave" }, { type: "openSubmit" }]);
     expect(reduceKey(atEnd, key("enter"))).toEqual([{ type: "walkLeave" }, { type: "openSubmit" }]);
   });
@@ -289,17 +368,24 @@ describe("review panel controls", () => {
   }
 
   test("observers may still collapse and resize the panel (it is view state, not a mutation)", () => {
+    // Arrange
     const observer = state({ readOnly: true });
+
+    // Assert
     expect(reduceKey(observer, key("b"))).toEqual([{ type: "cycleReviewPanel" }]);
     expect(reduceKey(observer, key("]"))).toEqual([{ type: "resizeReviewPanel", direction: 1 }]);
   });
 
   test("span mode still owns b as a span verb, not a panel cycle", () => {
+    // Assert
     expect(reduceKey(state({ spanMode: true }), key("b"))).toEqual([{ type: "spanKey", name: "b" }]);
   });
 
   test("the walk overlay keeps the brackets for stepping", () => {
+    // Arrange
     const walking = state({ view: "diff", overlay: "walk" });
+
+    // Assert
     expect(reduceKey(walking, key("]"))).toEqual([{ type: "walkForward" }]);
     expect(reduceKey(walking, key("["))).toEqual([{ type: "walkBack" }]);
   });
@@ -332,15 +418,21 @@ describe("read-only filter", () => {
   });
 
   test("navigation and annotation focus still work for observers", () => {
+    // Arrange
     const keyState = state({ readOnly: true });
+
+    // Assert
     expect(reduceKey(keyState, key("j"))).toEqual([{ type: "move", to: "down" }]);
     expect(reduceKey(keyState, key("n"))).toEqual([{ type: "nextAnnotation" }]);
     expect(reduceKey(keyState, key("q"))).toEqual([{ type: "exit" }]);
   });
 
   test("span-mode c/s are gated by key name even under a rebound keymap", () => {
+    // Arrange
     const rebound = { ...DEFAULT_KEYS, comment: ["m"], suggest: ["t"] };
     const keyState = state({ spanMode: true, readOnly: true, keys: rebound });
+
+    // Assert
     expect(reduceKey(keyState, key("c"))).toEqual([{ type: "status", message: "observer - read-only" }]);
     expect(reduceKey(keyState, key("s"))).toEqual([{ type: "status", message: "observer - read-only" }]);
   });

package/src/keymap.ts

@@ -18,6 +18,7 @@ export type Intent =
   | { type: "spanKey"; name: string }
   | { type: "openCompose"; kind: "comment" | "suggestion"; from: "cursor" | "span" }
   | { type: "openSubmit" }
+  | { type: "share" }
   | { type: "cut" }
   | { type: "edit" }
   | { type: "editCard" }
@@ -50,6 +51,15 @@ export interface KeyState {
   /** Loaded keymap (config.ts): action -> key combos. */
   keys: Record<string, string[]>;
   readOnly: boolean;
+  /**
+   * Owner-only verbs a share collaborator lacks (undefined = owner, allowed).
+   * A collaborator annotates but cannot edit the plan (cut / $EDITOR runs on
+   * the gateway) or submit an agent verdict (there is no agent on a share).
+   */
+  canEditPlan?: boolean;
+  canSubmitVerdict?: boolean;
+  /** Owner-only: publish the plan as a share. A collaborator never re-shares. */
+  canShare?: boolean;
   /** Layer that owns keys before the grammar runs. */
   overlay: "none" | "walk" | "compose" | "submit" | "completion-prompt" | "completion-counting";
   view: "inbox" | "plan" | "diff";
@@ -66,7 +76,7 @@ export interface KeyState {
 }
 
 /** Verbs that write session state; an observer never reaches their handlers. */
-const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit", "walk"]);
+const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit", "walk", "share"]);
 
 const SPAN_KEYS = ["l", "h", "w", "b", "$", "0"];
 
@@ -127,6 +137,12 @@ export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: strin
   const mutating = MUTATING_ACTIONS.has(action ?? "") || (state.spanMode && (name === "c" || name === "s"));
   if (state.readOnly && mutating) return status("observer - read-only");
 
+  // share is a session-level verb: it works from any view, owner only
+  if (action === "share") {
+    if (state.canShare === false) return status("only the plan owner can share");
+    return [{ type: "share" }];
+  }
+
   if (state.view === "inbox") return inboxGrammar(state, name);
   // span mode owns its single-letter keys (b slides the span back) before the
   // review-panel controls claim them
@@ -201,6 +217,8 @@ function planGrammar(state: KeyState, action: string | undefined, name: string):
     // the document selects, the rail edits: with a card selected, Cut deletes
     // the annotation and edit rewrites the card body in place
     if (state.hasFocusedAnnotation) return [action === "cut" ? { type: "removeAnnotation" } : { type: "editCard" }];
+    // editing the plan itself is the owner's verb - a collaborator only annotates
+    if (state.canEditPlan === false) return status("shared plan - edit it in your own copy");
     return [{ type: action }];
   }
   return annotationCluster(state, action) ?? [];
@@ -224,6 +242,10 @@ function annotationCluster(state: KeyState, action: string | undefined): Intent[
     if (state.resolved || !state.hasFocusedAnnotation) return [];
     return [{ type: "removeAnnotation" }];
   }
-  if (action === "submit") return state.resolved ? [] : [{ type: "openSubmit" }];
+  if (action === "submit") {
+    // a collaborator's notes union back as they go; there is no verdict to submit
+    if (state.canSubmitVerdict === false) return status("shared view - your notes save as you go; q to leave");
+    return state.resolved ? [] : [{ type: "openSubmit" }];
+  }
   return null;
 }

package/src/serve.test.ts

@@ -70,6 +70,7 @@ function sshCapture(port: number, until: (frame: string) => boolean, timeoutMs =
 
 describe("cueloop serve", () => {
   test("listens on localhost, persists a host key under CUELOOP_HOME/ssh", () => {
+    // Assert
     expect(handle.host).toBe("127.0.0.1");
     expect(handle.port).toBeGreaterThan(0);
     expect(handle.fingerprints.length).toBe(1);
@@ -78,7 +79,10 @@ describe("cueloop serve", () => {
   });
 
   test("an anonymous ssh client gets the observer TUI for the session", async () => {
+    // Act
     const bytes = await sshCapture(handle.port, (frame) => frame.includes("Rollout Plan") && frame.includes("observer"));
+
+    // Assert
     expect(bytes).toContain("cueloop");
     expect(bytes).toContain("Rollout Plan");
     // observer chrome, not the controller's mutating hint bar
@@ -86,10 +90,13 @@ describe("cueloop serve", () => {
   });
 
   test("two observers can watch at once", async () => {
+    // Act
     const [a, b] = await Promise.all([
       sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
       sshCapture(handle.port, (frame) => frame.includes("Rollout Plan")),
     ]);
+
+    // Assert
     expect(a).toContain("Rollout Plan");
     expect(b).toContain("Rollout Plan");
   });