@cueloop/client 0.1.0-alpha.9 → 0.1.0-alpha.90

package/src/keymap.ts

@@ -1,7 +1,7 @@
 /**
- * The keyboard grammar as a pure reducer (#70): view state in, intents out.
+ * The keyboard grammar as a pure reducer: view state in, intents out.
  * App builds a KeyState per key event, calls reduceKey, and dispatches the
- * intents to controller verbs and view-state setters - no branch bodies live
+ * intents to controller primitives and view-state setters - no branch bodies live
  * in the key handler. Diff and plan reviews share one path for annotation
  * navigation, deletion, and submit; the read-only rule is one gate here.
  */
@@ -9,44 +9,92 @@
 import { actionFor } from "./config";
 
 export type Intent =
-  | { t: "exit" }
-  | { t: "status"; msg: string }
-  | { t: "move"; to: "down" | "up" | "top" | "bottom" }
-  | { t: "inboxMove"; to: "down" | "up" }
-  | { t: "openSession" }
-  | { t: "startSpan" }
-  | { t: "spanKey"; name: string }
-  | { t: "openCompose"; kind: "comment" | "suggestion"; from: "cursor" | "span" }
-  | { t: "openSubmit" }
-  | { t: "cut" }
-  | { t: "edit" }
-  | { t: "editCard" }
-  | { t: "nextAnn" }
-  | { t: "prevAnn" }
-  | { t: "removeAnnotation" }
-  | { t: "deselect" }
-  | { t: "closeOverlay" }
-  | { t: "saveCompose" }
-  | { t: "submitVerdict" }
-  | { t: "cycleVerdict"; dir: -1 | 1 }
-  | { t: "finishReview" }
-  | { t: "optInAutoClose" }
-  | { t: "dismissCompletion" };
+  | { type: "exit" }
+  | { type: "status"; message: string }
+  | { type: "move"; to: "down" | "up" | "top" | "bottom" }
+  | { type: "inboxMove"; to: "down" | "up" }
+  | { type: "openSession" }
+  | { type: "requestDeleteSession" }
+  | { type: "openRename" }
+  | { type: "confirmDialog" }
+  | { type: "startSpan" }
+  | { type: "spanKey"; name: string }
+  | { type: "spanCut" }
+  | { type: "openSpanActions" }
+  | { type: "moveSpanAction"; direction: -1 | 1 }
+  | { type: "pickSpanAction"; index?: number }
+  | { type: "closeSpanActions" }
+  | { type: "openCompose"; kind: "comment"; from: "cursor" | "span" }
+  | { type: "openSubmit" }
+  | { type: "share" }
+  | { type: "cut" }
+  | { type: "edit" }
+  | { type: "editCard" }
+  | { type: "rejectHunk" }
+  | { type: "rejectChange" }
+  | { type: "restoreCuration" }
+  | { type: "foldFile" }
+  | { type: "unfoldFile" }
+  | { type: "toggleDiffView" }
+  | { type: "nextAnnotation" }
+  | { type: "prevAnnotation" }
+  | { type: "walkStart" }
+  | { type: "walkForward" }
+  | { type: "walkBack" }
+  | { type: "walkLeave" }
+  | { type: "removeAnnotation" }
+  | { type: "deselect" }
+  | { type: "closeOverlay" }
+  | { type: "saveCompose" }
+  | { type: "submitMessage" }
+  | { type: "cycleMessage"; direction: -1 | 1 }
+  | { type: "finishReview" }
+  | { type: "optInAutoClose" }
+  | { type: "dismissCompletion" }
+  | { type: "toggleTree" }
+  | { type: "treeMove"; direction: -1 | 1 }
+  | { type: "treeGo" }
+  | { type: "treeBranch" }
+  | { type: "treeLabel" }
+  | { type: "treeFork" }
+  | { type: "treeForkShare" };
 
 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 primitives 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 message (there is no agent on a share).
+   */
+  canEditPlan?: boolean;
+  canSubmitMessage?: 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" | "compose" | "submit" | "completion-prompt" | "completion-counting";
+  overlay:
+    | "none"
+    | "walk"
+    | "compose"
+    | "submit"
+    | "confirm"
+    | "prompt"
+    | "spanActions"
+    | "completion-prompt"
+    | "completion-counting";
   view: "inbox" | "plan" | "diff";
   /** Plan-only span selection sub-mode. */
   spanMode: boolean;
+  /** The walk cursor sits on the end card - return offers the submit action. */
+  walkAtEnd: boolean;
   resolved: boolean;
   hasInboxItems: boolean;
   annotationCount: number;
@@ -55,106 +103,278 @@ export interface KeyState {
   cursorAnnotatable: boolean;
 }
 
-/** Verbs that write session state; an observer never reaches their handlers. */
-const MUTATING_ACTIONS = new Set(["comment", "suggest", "cut", "edit", "delete_annotation", "submit"]);
+/** Primitives that write session state; an observer never reaches their handlers. */
+const MUTATING_ACTIONS = new Set([
+  "comment",
+  "cut",
+  "edit",
+  "delete_annotation",
+  "submit",
+  "walk",
+  "share",
+  "reject_hunk",
+  "restore_curation",
+]);
 
-const SPAN_KEYS = ["l", "h", "w", "b", "$", "0"];
+const SPAN_KEYS = new Set(["l", "h", "w", "b", "$", "0"]);
 
-function status(msg: string): Intent[] {
-  return [{ t: "status", msg }];
+function status(message: string): Intent[] {
+  return [{ type: "status", message }];
 }
 
-export function reduceKey(state: KeyState, key: KeyInput): Intent[] {
+/**
+ * Reduce one key event to intents. `resolvedAction` is the binding-layer
+ * resolution (key-bindings.ts over @opentui/keymap) when the caller has one;
+ * without it the reducer falls back to the plain reverse lookup, so the
+ * grammar stays testable as a pure function.
+ */
+export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: string): Intent[] {
   const name = key.name;
-  // compose/submit overlays own the keys via focused inputs; only escape,
-  // return, and verdict arrows route through the grammar
-  if (state.overlay === "compose" || state.overlay === "submit") {
-    if (name === "escape") return [{ t: "closeOverlay" }];
-    if (name === "return" || name === "enter") {
-      return [state.overlay === "compose" ? { t: "saveCompose" } : { t: "submitVerdict" }];
-    }
-    if (state.overlay === "submit" && (name === "left" || name === "right")) {
-      return [{ t: "cycleVerdict", dir: name === "left" ? -1 : 1 }];
-    }
-    return [];
-  }
-  if (state.overlay === "completion-prompt" || state.overlay === "completion-counting") {
-    if (name === "return" || name === "enter" || name === "q") return [{ t: "finishReview" }];
-    if (name === "a" && state.overlay === "completion-prompt") return [{ t: "optInAutoClose" }];
-    if (name === "escape") return [{ t: "dismissCompletion" }];
-    return [];
-  }
-  const action = actionFor(state.keys, name, key.shift);
-  if (action === "quit") return [{ t: "exit" }];
+  const overlayGrammar = overlayGrammars[state.overlay];
+
+  if (overlayGrammar) return overlayGrammar(state, key);
+  const action = resolvedAction ?? actionFor(state.keys, name, key.shift);
+
+  if (action === "quit") return [{ type: "exit" }];
   // the ONE read-only rule: any mutating attempt answers instead of acting
-  // (span-mode c/s are hardwired keys, so they gate by name as well)
-  const mutating = MUTATING_ACTIONS.has(action ?? "") || (state.spanMode && (name === "c" || name === "s"));
+  // (span-mode c, x, and a are hardwired keys, so they gate by name as well)
+  const mutating =
+    MUTATING_ACTIONS.has(action ?? "") ||
+    (state.spanMode && (name === "c" || name === "x" || name === "a"));
+
   if (state.readOnly && mutating) return status("observer - read-only");
 
+  // share is a session-level primitive: 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)
+  if (state.spanMode) return spanGrammar(state, name);
   if (state.view === "diff") return diffGrammar(state, action);
-  if (state.spanMode) return spanGrammar(name);
+
   return planGrammar(state, action, name);
 }
 
+type OverlayGrammar = (state: KeyState, key: KeyInput) => Intent[];
+
+const overlayGrammars: Partial<Record<KeyState["overlay"], OverlayGrammar>> = {
+  compose: composeOverlayGrammar,
+  submit: submitOverlayGrammar,
+  confirm: confirmOverlayGrammar,
+  prompt: promptOverlayGrammar,
+  spanActions: spanActionsOverlayGrammar,
+  "completion-prompt": completionOverlayGrammar,
+  "completion-counting": completionOverlayGrammar,
+  walk: walkOverlayGrammar,
+};
+
+function composeOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (name === "return" || name === "enter") {
+    // 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 (key.shift || key.meta) return [];
+
+    return [{ type: "saveCompose" }];
+  }
+
+  return [];
+}
+
+function submitOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (name === "left" || name === "right") {
+    return [{ type: "cycleMessage", direction: name === "left" ? -1 : 1 }];
+  }
+
+  return [];
+}
+
+function confirmOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter") return [{ type: "confirmDialog" }];
+  if (name === "escape") return [{ type: "closeOverlay" }];
+
+  return [];
+}
+
+function promptOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter") return [{ type: "confirmDialog" }];
+  if (name === "escape") return [{ type: "closeOverlay" }];
+
+  return [];
+}
+
+function spanActionsOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "j" || name === "down") return [{ type: "moveSpanAction", direction: 1 }];
+  if (name === "k" || name === "up") return [{ type: "moveSpanAction", direction: -1 }];
+  if (name === "return" || name === "enter") return [{ type: "pickSpanAction" }];
+  if (name === "escape") return [{ type: "closeSpanActions" }];
+
+  return [];
+}
+
+function completionOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter" || name === "q") return [{ type: "finishReview" }];
+  if (name === "a") return [{ type: "optInAutoClose" }];
+  if (name === "escape") return [{ type: "dismissCompletion" }];
+
+  return [];
+}
+
+function walkOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "]") return [{ type: "walkForward" }];
+  if (name === "[") return [{ type: "walkBack" }];
+  if (name === "escape") return [{ type: "walkLeave" }];
+  if ((name === "return" || name === "enter") && state.walkAtEnd) {
+    return [{ type: "walkLeave" }, { type: "openSubmit" }];
+  }
+  if (name === "q") return [{ type: "exit" }];
+
+  return [];
+}
+
 function inboxGrammar(state: KeyState, name: string): Intent[] {
   if (!state.hasInboxItems) return [];
-  if (name === "j" || name === "down") return [{ t: "inboxMove", to: "down" }];
-  if (name === "k" || name === "up") return [{ t: "inboxMove", to: "up" }];
-  if (name === "return" || name === "enter") return [{ t: "openSession" }];
+  if (name === "j" || name === "down") return [{ type: "inboxMove", to: "down" }];
+  if (name === "k" || name === "up") return [{ type: "inboxMove", to: "up" }];
+  if (name === "return" || name === "enter") return [{ type: "openSession" }];
+  if (name === "d") return [{ type: "requestDeleteSession" }];
+
   return [];
 }
 
 function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
-  const nav = navIntent(action);
-  if (nav) return nav;
+  const navigation = navigationIntent(action);
+
+  if (navigation) return navigation;
+  if (action === "walk") {
+    // marking viewed writes the session record, so a resolved review answers
+    if (state.resolved) return status("review submitted - read-only");
+
+    return [{ type: "walkStart" }];
+  }
   if (action === "comment") {
     if (state.resolved) return status("review submitted - read-only");
     if (!state.cursorAnnotatable) return status("move to a code line to comment");
-    return [{ t: "openCompose", kind: "comment", from: "cursor" }];
+
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  // cut rejects the change under the cursor, reject_hunk the whole hunk; both
+  // write the working copy, so they gate on owner like a plan edit.
+  if (action === "cut" || action === "reject_hunk") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return status("only the diff owner can curate hunks");
+
+    return [{ type: action === "reject_hunk" ? "rejectHunk" : "rejectChange" }];
+  }
+  const viewToggle = viewToggleIntent(action);
+
+  if (viewToggle) return viewToggle;
+  // restore un-does a curated-out rejection from the rail; same owner gate as reject
+  if (action === "restore_curation") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return status("only the diff owner can curate hunks");
+
+    return [{ type: "restoreCuration" }];
   }
   const shared = annotationCluster(state, action);
+
   if (shared) return shared;
-  if (action === "span" || action === "cut" || action === "edit" || action === "suggest") {
-    return status("plan-only verb - diff review uses c on a line");
+  if (action === "span" || action === "edit") {
+    return status("plan-only primitive - diff review uses c on a line");
   }
+
   return [];
 }
 
-function spanGrammar(name: string): Intent[] {
-  if (name === "escape") return [{ t: "closeOverlay" }];
-  if (SPAN_KEYS.includes(name)) return [{ t: "spanKey", name }];
-  if (name === "c" || name === "s") {
-    return [{ t: "openCompose", kind: name === "s" ? "suggestion" : "comment", from: "span" }];
+function spanGrammar(state: KeyState, name: string): Intent[] {
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (SPAN_KEYS.has(name)) return [{ type: "spanKey", name }];
+  // c comments, x cuts, a opens quick-actions - all mutate, so a resolved
+  // review is read-only, like the plan grammar
+  if (name === "c" || name === "x" || name === "a") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (name === "c") return [{ type: "openCompose", kind: "comment", from: "span" }];
+    if (name === "a") return [{ type: "openSpanActions" }];
+    if (state.canEditPlan === false) return [];
+
+    return [{ type: "spanCut" }];
   }
+
   return [];
 }
 
 function planGrammar(state: KeyState, action: string | undefined, name: string): Intent[] {
-  const nav = navIntent(action);
-  if (nav) return nav;
-  if (name === "escape") return [{ t: "deselect" }];
-  if (action === "span") return state.cursorAnnotatable ? [{ t: "startSpan" }] : [];
-  if (action === "comment" || action === "suggest") {
+  const navigation = navigationIntent(action);
+
+  if (navigation) return navigation;
+  if (action === "walk") return status("the guided walk is a diff-review mode");
+  if (name === "escape") return [{ type: "deselect" }];
+  if (action === "span") return state.cursorAnnotatable ? [{ type: "startSpan" }] : [];
+  if (action === "comment") {
     if (state.resolved) return status("review submitted - read-only");
     if (!state.cursorAnnotatable) return status("text is cut - restore it first");
-    return [{ t: "openCompose", kind: action === "suggest" ? "suggestion" : "comment", from: "cursor" }];
+
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  // restore un-does a rail removal (a cut block); a plan edit, so owner-only
+  if (action === "restore_curation") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return [];
+
+    return [{ type: "restoreCuration" }];
   }
   if (action === "cut" || action === "edit") {
     if (state.resolved) return status("review submitted - read-only");
     // 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" ? { t: "removeAnnotation" } : { t: "editCard" }];
-    return [{ t: action }];
+    if (state.hasFocusedAnnotation)
+      return [action === "cut" ? { type: "removeAnnotation" } : { type: "editCard" }];
+    // editing the plan itself is the owner's primitive; a share viewer only annotates,
+    // and has no edit affordance, so the key is silent rather than a nag
+    if (state.canEditPlan === false) return [];
+
+    return [{ type: action }];
   }
+
   return annotationCluster(state, action) ?? [];
 }
 
 /** Cursor movement is the same intent everywhere; views clamp their own bounds. */
-function navIntent(action: string | undefined): Intent[] | null {
+function navigationIntent(action: string | undefined): Intent[] | null {
   if (action === "down" || action === "up" || action === "top" || action === "bottom") {
-    return [{ t: "move", to: action }];
+    return [{ type: "move", to: action }];
   }
+
+  return null;
+}
+
+/** Ungated view toggles in the diff: right folds a file to its band, left unfolds it, s flips
+ *  split/stacked (split lays out only when the Changes pane is wide/zoomed). */
+function viewToggleIntent(action: string | undefined): Intent[] | null {
+  if (action === "collapse_file") return [{ type: "foldFile" }];
+  if (action === "expand_file") return [{ type: "unfoldFile" }];
+  if (action === "split_diff") return [{ type: "toggleDiffView" }];
+
   return null;
 }
 
@@ -162,12 +382,26 @@ function navIntent(action: string | undefined): Intent[] | null {
 function annotationCluster(state: KeyState, action: string | undefined): Intent[] | null {
   if (action === "next_annotation" || action === "prev_annotation") {
     if (!state.annotationCount) return status("no annotations");
-    return [{ t: action === "next_annotation" ? "nextAnn" : "prevAnn" }];
+
+    return [{ type: action === "next_annotation" ? "nextAnnotation" : "prevAnnotation" }];
   }
   if (action === "delete_annotation") {
     if (state.resolved || !state.hasFocusedAnnotation) return [];
-    return [{ t: "removeAnnotation" }];
+
+    return [{ type: "removeAnnotation" }];
   }
-  if (action === "submit") return state.resolved ? [] : [{ t: "openSubmit" }];
+  if (action === "rename") {
+    if (!state.hasFocusedAnnotation) return status("select a collaborator's note to rename them");
+
+    return [{ type: "openRename" }];
+  }
+  if (action === "submit") {
+    // a collaborator's notes union back as they go; there is no message to submit
+    if (state.canSubmitMessage === false)
+      return status("shared view - your notes save as you go; q to leave");
+
+    return state.resolved ? [] : [{ type: "openSubmit" }];
+  }
+
   return null;
 }

package/src/kitty-image.test.ts

@@ -0,0 +1,66 @@
+/** Kitty emission guards: the image sits beneath painted cells, and every put reuses one placement id so repeated frames REPLACE the placement instead of stacking a new one each frame (the prototype's per-frame lag/ghosting regression). Transmit medium is file locally and base64 over ssh. */
+
+import { describe, expect, test } from "bun:test";
+import { placeKittyImage, resolveTransmitMedium, transmitKittyImage } from "./kitty-image";
+
+const REGION = { column: 2, row: 3, columns: 40, rows: 12 };
+
+describe("kitty image placement", () => {
+  test("places the prototype below cells with painted backgrounds", () => {
+    // Arrange
+    const writes: string[] = [];
+
+    // Act
+    transmitKittyImage((chunk) => writes.push(chunk), new Uint8Array([1]), REGION, 811);
+    placeKittyImage((chunk) => writes.push(chunk), REGION, 811);
+
+    // Assert
+    expect(writes).toHaveLength(2);
+    expect(writes[0]).toContain("z=-1073741825");
+    expect(writes[1]).toContain("z=-1073741825");
+  });
+
+  test("every frame reuses one placement id, so repeated puts replace rather than stack", () => {
+    // Arrange
+    const writes: string[] = [];
+    const write = (chunk: string): void => void writes.push(chunk);
+
+    // Act - one transmit then many re-places, as the per-frame paint loop does
+    transmitKittyImage(write, new Uint8Array([1]), REGION, 811, "base64");
+    for (let frame = 0; frame < 5; frame++) placeKittyImage(write, REGION, 811);
+
+    // Assert - a stable placement id p=1 on the transmit and every place
+    expect(writes[0]).toContain("i=811,p=1");
+    for (const placement of writes.slice(1)) expect(placement).toContain("i=811,p=1");
+  });
+
+  test("base64 transmit chunks the payload; file transmit hands over a path once", () => {
+    // Arrange
+    const big = new Uint8Array(9000).fill(1);
+    const base64Writes: string[] = [];
+    const fileWrites: string[] = [];
+
+    // Act
+    transmitKittyImage((chunk) => base64Writes.push(chunk), big, REGION, 811, "base64");
+    transmitKittyImage((chunk) => fileWrites.push(chunk), big, REGION, 811, "file");
+
+    // Assert - base64 inlines the data (a=T without t=), file references a temp path (t=t)
+    expect(base64Writes[0]).toContain("a=T");
+    expect(base64Writes[0]).not.toContain("t=t");
+    expect(fileWrites[0]).toContain("t=t");
+  });
+});
+
+describe("resolveTransmitMedium", () => {
+  test("defaults to base64; file transfer is opt-in and never over ssh", () => {
+    // Assert
+    expect(resolveTransmitMedium({})).toBe("base64");
+    expect(resolveTransmitMedium({ CUELOOP_KITTY_FILE: "1" })).toBe("file");
+    expect(
+      resolveTransmitMedium({
+        CUELOOP_KITTY_FILE: "1",
+        SSH_CONNECTION: "1.2.3.4 5 6 7",
+      }),
+    ).toBe("base64");
+  });
+});