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

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";
@@ -25,11 +21,12 @@ function state(patch: Partial<KeyState> = {}): KeyState {
   };
 }
 
-function key(name: string, shift = false): { name: string; shift: boolean } {
-  return { name, shift };
+function key(name: string, shift = false, meta = false): { name: string; shift: boolean; meta: boolean } {
+  return { name, shift, meta };
 }
 
 describe("compose overlay", () => {
+  // Arrange
   const keyState = state({ overlay: "compose" });
   const table: [string, Intent[]][] = [
     ["escape", [{ type: "closeOverlay" }]],
@@ -45,16 +42,26 @@ describe("compose overlay", () => {
       expect(reduceKey(keyState, key(name))).toEqual(expected);
     });
   }
+
+  // ⌥/Alt+⏎ (meta) and shift+⏎ insert a newline in the composer, so the
+  // grammar must not save on them; only a bare ⏎ saves.
+  test("option/alt+return (meta) does not save - the textarea inserts a newline", () => {
+    expect(reduceKey(keyState, key("return", false, true))).toEqual([]);
+  });
+  test("shift+return does not save - the textarea inserts a newline", () => {
+    expect(reduceKey(keyState, key("return", true, false))).toEqual([]);
+  });
 });
 
 describe("submit overlay", () => {
+  // Arrange
   const keyState = state({ overlay: "submit" });
   const table: [string, Intent[]][] = [
     ["escape", [{ type: "closeOverlay" }]],
     ["return", [{ type: "submitVerdict" }]],
     ["enter", [{ type: "submitVerdict" }]],
-    ["left", [{ type: "cycleVerdict", dir: -1 }]],
-    ["right", [{ type: "cycleVerdict", dir: 1 }]],
+    ["left", [{ type: "cycleVerdict", direction: -1 }]],
+    ["right", [{ type: "cycleVerdict", direction: 1 }]],
     ["j", []],
     ["q", []],
   ];
@@ -66,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[]][] = [
@@ -88,6 +96,7 @@ describe("completion overlay", () => {
 });
 
 describe("inbox mode", () => {
+  // Arrange
   const keyState = state({ view: "inbox" });
   const table: [string, Intent[]][] = [
     ["j", [{ type: "inboxMove", to: "down" }]],
@@ -107,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([]);
     }
@@ -115,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" }]],
@@ -145,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" }]);
     }
@@ -154,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" }]],
@@ -197,6 +278,7 @@ describe("span mode", () => {
 });
 
 describe("diff mode", () => {
+  // Arrange
   const keyState = state({ view: "diff" });
   const table: [string, Intent[]][] = [
     ["j", [{ type: "move", to: "down" }]],
@@ -220,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" },
     ]);
@@ -231,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" },
@@ -241,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" }]],
@@ -259,12 +344,53 @@ 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" }]);
   });
 });
 
+describe("review panel controls", () => {
+  const table: [string, Intent[]][] = [
+    ["b", [{ type: "cycleReviewPanel" }]],
+    ["]", [{ type: "resizeReviewPanel", direction: 1 }]],
+    ["[", [{ type: "resizeReviewPanel", direction: -1 }]],
+  ];
+  for (const view of ["plan", "diff"] as const) {
+    for (const [name, expected] of table) {
+      test(`${view} ${name} -> ${JSON.stringify(expected)}`, () => {
+        expect(reduceKey(state({ view }), key(name))).toEqual(expected);
+      });
+    }
+  }
+
+  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" }]);
+  });
+});
+
 describe("duplicated-branch collapse", () => {
   test("plan and diff produce the same intents for annotation nav, delete, and submit", () => {
     for (const patch of [
@@ -292,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" }
@@ -32,20 +33,33 @@ export type Intent =
   | { type: "closeOverlay" }
   | { type: "saveCompose" }
   | { type: "submitVerdict" }
-  | { type: "cycleVerdict"; dir: -1 | 1 }
+  | { type: "cycleVerdict"; direction: -1 | 1 }
   | { type: "finishReview" }
   | { type: "optInAutoClose" }
-  | { type: "dismissCompletion" };
+  | { type: "dismissCompletion" }
+  | { type: "cycleReviewPanel" }
+  | { type: "resizeReviewPanel"; direction: -1 | 1 };
 
 export interface KeyInput {
   name: string;
   shift: boolean;
+  /** Option/Alt arrives as `meta` in this terminal stack (never as a raw alt). */
+  meta?: boolean;
 }
 
 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";
@@ -62,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"];
 
@@ -83,10 +97,17 @@ export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: strin
   if (state.overlay === "compose" || state.overlay === "submit") {
     if (name === "escape") return [{ type: "closeOverlay" }];
     if (name === "return" || name === "enter") {
-      return [state.overlay === "compose" ? { type: "saveCompose" } : { type: "submitVerdict" }];
+      // In the composer, ⌥/Alt+⏎ (meta) and shift+⏎ insert a newline - the
+      // focused textarea owns that; only a bare ⏎ saves. The submit overlay
+      // keeps its plain ⏎ submit.
+      if (state.overlay === "compose") {
+        if (key.shift || key.meta) return [];
+        return [{ type: "saveCompose" }];
+      }
+      return [{ type: "submitVerdict" }];
     }
     if (state.overlay === "submit" && (name === "left" || name === "right")) {
-      return [{ type: "cycleVerdict", dir: name === "left" ? -1 : 1 }];
+      return [{ type: "cycleVerdict", direction: name === "left" ? -1 : 1 }];
     }
     return [];
   }
@@ -116,12 +137,32 @@ 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);
-  if (state.view === "diff") return diffGrammar(state, action);
+  // span mode owns its single-letter keys (b slides the span back) before the
+  // review-panel controls claim them
   if (state.spanMode) return spanGrammar(name);
+  // the review panel rides both plan and diff reviews; collapsing and resizing
+  // are view state, so the read-only gate above lets them through
+  const reviewPanel = reviewPanelGrammar(action);
+  if (reviewPanel) return reviewPanel;
+  if (state.view === "diff") return diffGrammar(state, action);
   return planGrammar(state, action, name);
 }
 
+/** The review-panel controls: cycle the mode, widen and narrow the rail. */
+function reviewPanelGrammar(action: string | undefined): Intent[] | null {
+  if (action === "review_cycle") return [{ type: "cycleReviewPanel" }];
+  if (action === "review_wider") return [{ type: "resizeReviewPanel", direction: 1 }];
+  if (action === "review_narrower") return [{ type: "resizeReviewPanel", direction: -1 }];
+  return null;
+}
+
 function inboxGrammar(state: KeyState, name: string): Intent[] {
   if (!state.hasInboxItems) return [];
   if (name === "j" || name === "down") return [{ type: "inboxMove", to: "down" }];
@@ -176,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) ?? [];
@@ -199,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/review-panel.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+import {
+  REVIEW_DEFAULT_WIDTH,
+  REVIEW_MAX_WIDTH,
+  REVIEW_MIN_WIDTH,
+  REVIEW_PLAN_MIN_WIDTH,
+  REVIEW_RESIZE_STEP,
+  clampWidth,
+  cycleReviewPanelMode,
+  maxWidthForTerminal,
+  resolveReviewWidth,
+  reviewRowsToDivider,
+  toggleReviewPanelMode,
+  widthFromMouseColumn,
+} from "./review-panel";
+
+describe("clampWidth", () => {
+  test("keeps a width inside the bounds untouched", () => {
+    expect(clampWidth(REVIEW_DEFAULT_WIDTH)).toBe(REVIEW_DEFAULT_WIDTH);
+  });
+
+  test("clamps below the minimum and above the maximum", () => {
+    expect(clampWidth(REVIEW_MIN_WIDTH - 10)).toBe(REVIEW_MIN_WIDTH);
+    expect(clampWidth(REVIEW_MAX_WIDTH + 10)).toBe(REVIEW_MAX_WIDTH);
+  });
+
+  test("rounds a fractional column to a whole one", () => {
+    expect(clampWidth(30.7)).toBe(31);
+  });
+
+  test("honors explicit bounds", () => {
+    expect(clampWidth(100, 10, 20)).toBe(20);
+    expect(clampWidth(5, 10, 20)).toBe(10);
+  });
+});
+
+describe("cycleReviewPanelMode", () => {
+  test("cycles expanded -> compact -> hidden -> expanded", () => {
+    expect(cycleReviewPanelMode("expanded")).toBe("compact");
+    expect(cycleReviewPanelMode("compact")).toBe("hidden");
+    expect(cycleReviewPanelMode("hidden")).toBe("expanded");
+  });
+});
+
+describe("toggleReviewPanelMode", () => {
+  test("the chevron toggles only between expanded and compact, never hidden", () => {
+    expect(toggleReviewPanelMode("expanded")).toBe("compact");
+    expect(toggleReviewPanelMode("compact")).toBe("expanded");
+    // a hidden panel has no chevron; a stray toggle still opens it
+    expect(toggleReviewPanelMode("hidden")).toBe("expanded");
+  });
+});
+
+describe("widthFromMouseColumn", () => {
+  test("measures the rail from the mouse column to the right edge", () => {
+    // divider dragged to column 80 of a 120-wide terminal -> a 40-col rail
+    expect(widthFromMouseColumn(80, 120)).toBe(40);
+  });
+
+  test("clamps the dragged width to the bounds", () => {
+    expect(widthFromMouseColumn(0, 120)).toBe(REVIEW_MAX_WIDTH);
+    expect(widthFromMouseColumn(119, 120)).toBe(REVIEW_MIN_WIDTH);
+  });
+
+  test("cannot drag the rail wide enough to starve the plan on a narrow terminal", () => {
+    // dragging to the far left edge of a 60-col terminal still leaves the plan its minimum
+    expect(widthFromMouseColumn(0, 60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+
+  test("the resize step widens and narrows within the clamp", () => {
+    expect(clampWidth(REVIEW_DEFAULT_WIDTH + REVIEW_RESIZE_STEP)).toBe(REVIEW_DEFAULT_WIDTH + REVIEW_RESIZE_STEP);
+    expect(clampWidth(REVIEW_MIN_WIDTH - REVIEW_RESIZE_STEP)).toBe(REVIEW_MIN_WIDTH);
+  });
+});
+
+describe("maxWidthForTerminal", () => {
+  test("allows the full rail on a wide terminal", () => {
+    expect(maxWidthForTerminal(120)).toBe(REVIEW_MAX_WIDTH);
+  });
+
+  test("reserves the plan its minimum on a narrow terminal", () => {
+    // 60-col terminal: 30 for the plan and 1 for the divider leaves 29 for the rail
+    expect(maxWidthForTerminal(60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+
+  test("never drops below the rail minimum, however narrow the terminal", () => {
+    expect(maxWidthForTerminal(40)).toBe(REVIEW_MIN_WIDTH);
+  });
+});
+
+describe("resolveReviewWidth", () => {
+  test("leaves a width that already fits untouched", () => {
+    expect(resolveReviewWidth(REVIEW_DEFAULT_WIDTH, 120)).toBe(REVIEW_DEFAULT_WIDTH);
+  });
+
+  test("shrinks a wide persisted width so the plan keeps its room", () => {
+    // a saved 50-col rail on a 60-col terminal would leave the plan 9 cols; clamp it back
+    expect(resolveReviewWidth(REVIEW_MAX_WIDTH, 60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+});
+
+describe("reviewRowsToDivider", () => {
+  test("builds one vertical glyph per row", () => {
+    expect(reviewRowsToDivider(3)).toBe("│\n│\n│");
+  });
+
+  test("never collapses to an empty column", () => {
+    expect(reviewRowsToDivider(0)).toBe("│");
+    expect(reviewRowsToDivider(-4)).toBe("│");
+  });
+});

package/src/review-panel.ts

@@ -0,0 +1,76 @@
+/**
+ * Pure geometry and state for the resizable review panel. The panel shows the
+ * review rail in one of three modes and the expanded rail resizes within a
+ * clamp; App owns the React state and the mouse wiring, this module owns the
+ * arithmetic so the layout math stays unit-tested and out of the JSX. Bounds
+ * and the compact width carry over verbatim from the approved prototype.
+ */
+
+/** Expanded (full rail), compact (count + dots strip), or hidden (nothing). */
+export type ReviewPanelMode = "expanded" | "compact" | "hidden";
+
+/** Expanded-rail width bounds, in terminal columns. */
+export const REVIEW_MIN_WIDTH = 24;
+export const REVIEW_MAX_WIDTH = 50;
+export const REVIEW_DEFAULT_WIDTH = 34;
+/**
+ * Columns the plan/diff column keeps for itself: the expanded rail yields past
+ * this so a narrow terminal (or a wide persisted width) can never crowd the
+ * plan out to nothing - the whole reason the panel is resizable. On terminals
+ * wide enough for the full 50-col rail this bound never binds.
+ */
+export const REVIEW_PLAN_MIN_WIDTH = 30;
+/** The compact strip is a fixed narrow column: count on top, one dot per card. */
+export const REVIEW_COMPACT_WIDTH = 6;
+/** Keyboard resize step, in columns, for the widen/narrow keys. */
+export const REVIEW_RESIZE_STEP = 2;
+
+/** Round a desired width to a whole column and clamp it to the bounds. */
+export function clampWidth(desiredWidth: number, min = REVIEW_MIN_WIDTH, max = REVIEW_MAX_WIDTH): number {
+  return Math.max(min, Math.min(max, Math.round(desiredWidth)));
+}
+
+/**
+ * The widest the expanded rail may be on a given terminal, reserving the plan
+ * its minimum and one column for the divider. Never drops below REVIEW_MIN_WIDTH
+ * (an extremely narrow terminal is the auto-collapse case, handled elsewhere).
+ */
+export function maxWidthForTerminal(terminalWidth: number): number {
+  return Math.max(REVIEW_MIN_WIDTH, Math.min(REVIEW_MAX_WIDTH, terminalWidth - REVIEW_PLAN_MIN_WIDTH - 1));
+}
+
+/** Clamp a desired rail width to the bounds AND the terminal, so the plan keeps its room. */
+export function resolveReviewWidth(desiredWidth: number, terminalWidth: number): number {
+  return clampWidth(desiredWidth, REVIEW_MIN_WIDTH, maxWidthForTerminal(terminalWidth));
+}
+
+/** The keybinding cycle: expanded -> compact -> hidden -> expanded. */
+export function cycleReviewPanelMode(mode: ReviewPanelMode): ReviewPanelMode {
+  return mode === "expanded" ? "compact" : mode === "compact" ? "hidden" : "expanded";
+}
+
+/**
+ * The clickable chevron toggles only between expanded and compact - hidden is
+ * reachable by keybinding alone, so it never leaves a leftover tab behind. A
+ * toggle from hidden still opens the panel rather than doing nothing.
+ */
+export function toggleReviewPanelMode(mode: ReviewPanelMode): ReviewPanelMode {
+  return mode === "expanded" ? "compact" : "expanded";
+}
+
+/**
+ * Rail width from an absolute mouse column while dragging the divider: the rail
+ * spans from the mouse column to the terminal's right edge, then clamps.
+ */
+export function widthFromMouseColumn(mouseColumn: number, terminalWidth: number): number {
+  return resolveReviewWidth(terminalWidth - mouseColumn, terminalWidth);
+}
+
+/**
+ * The divider is a single-column stack of vertical glyphs (a text block, not a
+ * bordered box - a one-column box with a border renders a full box). One glyph
+ * per row, at least one so the column never collapses.
+ */
+export function reviewRowsToDivider(rows: number): string {
+  return Array.from({ length: Math.max(1, rows) }, () => "│").join("\n");
+}

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