@cueloop/client 0.1.0-alpha.64 → 0.1.0-alpha.65

package/src/diff-hunk-curate.ts

@@ -13,16 +13,12 @@
  * the stored git patch and the model split hunks differently.
  */
 
-import { parseDiffFromFile, diffAcceptRejectHunk, type FileDiffMetadata } from "@pierre/diffs";
-import { unifiedDiffText, type DiffFileContents, type DiffFileStatus } from "@cueloop/schema";
+import type { FileDiffMetadata } from "@pierre/diffs";
+import type { HunkRejection } from "@cueloop/schema";
 import type { DiffRow } from "./view-diff";
 
-/** One reject decision; `changeIndex` absent rejects the whole hunk. */
-export interface HunkRejection {
-  path: string;
-  hunkIndex: number;
-  changeIndex?: number;
-}
+export { curateDiff, parseFileDiff } from "@cueloop/daemon/curate";
+export type { HunkRejection } from "@cueloop/schema";
 
 /** Which side of the diff a line number addresses. */
 type DiffSide = "addition" | "deletion";
@@ -34,24 +30,6 @@ export interface LocatedLine {
   changeIndex?: number;
 }
 
-/**
- * Context lines around each change. Matching git's default (3) makes the model
- * split hunks like the rendered working-tree patch does; git's coalescing can
- * still merge adjacent hunks differently, but the row is mapped by absolute line
- * number (not by counting hunks), so a whole-hunk reject can only ever span the
- * model hunk it lands in - never the wrong file or a crash.
- */
-const DIFF_CONTEXT = 3;
-
-/** Parse one file's full contents into a non-partial diff model. */
-export function parseFileDiff(file: DiffFileContents): FileDiffMetadata {
-  return parseDiffFromFile(
-    { name: file.path, contents: file.oldContents },
-    { name: file.path, contents: file.newContents },
-    { context: DIFF_CONTEXT },
-  );
-}
-
 /**
  * Resolve a 1-based file line on one side to its hunk and, when the line is
  * part of a change block, that block's `hunkContent` index.
@@ -173,81 +151,3 @@ export function isRowRejected(
       (rejection.changeIndex === undefined || rejection.changeIndex === located.changeIndex),
   );
 }
-
-/**
- * Apply one file's rejections and return its curated patch, or null when the
- * curated content equals the old content (every change rejected - no patch).
- * Whole-hunk rejections supersede change-level ones for the same hunk. Because
- * `diffAcceptRejectHunk` returns a model with the same hunk/content shape, the
- * indices stay valid across calls; they are applied high-to-low regardless, so
- * the order is deterministic.
- */
-function curateFilePatch(file: DiffFileContents, rejections: HunkRejection[]): string | null {
-  let model = parseFileDiff(file);
-  const wholeHunks = new Set(
-    rejections
-      .filter((rejection) => rejection.changeIndex === undefined)
-      .map((rejection) => rejection.hunkIndex),
-  );
-
-  for (const hunkIndex of [...wholeHunks].sort((a, b) => b - a)) {
-    model = diffAcceptRejectHunk(model, hunkIndex, "reject");
-  }
-  const changeRejections = rejections
-    .filter(
-      (rejection) => rejection.changeIndex !== undefined && !wholeHunks.has(rejection.hunkIndex),
-    )
-    .sort((a, b) => b.hunkIndex - a.hunkIndex || b.changeIndex! - a.changeIndex!);
-
-  for (const rejection of changeRejections) {
-    model = diffAcceptRejectHunk(model, rejection.hunkIndex, {
-      type: "reject",
-      changeIndex: rejection.changeIndex!,
-    });
-  }
-  const curatedNew = model.additionLines.join("");
-
-  if (curatedNew === file.oldContents) return null;
-  const patch = unifiedDiffText(file.oldContents, curatedNew, file.path);
-
-  if (patch === null) return null;
-
-  return withFileStateHeaders(patch, file.path, file.status, curatedNew);
-}
-
-/**
- * Point the diff headers at /dev/null for a created or fully-deleted file so the
- * curated patch applies. git's status - not empty contents - decides existence,
- * so editing an existing empty file stays a modify; a deletion whose removals
- * were partly restored also falls back to a modify.
- */
-function withFileStateHeaders(
-  patch: string,
-  path: string,
-  status: DiffFileStatus,
-  curatedNew: string,
-): string {
-  if (status === "added") return patch.replace(`--- a/${path}`, "--- /dev/null");
-  if (status === "deleted" && curatedNew === "") {
-    return patch.replace(`+++ b/${path}`, "+++ /dev/null");
-  }
-
-  return patch;
-}
-
-/**
- * The curated unified-diff patch of the accepted changes across every file.
- * Files with no net change (unchanged, or with all changes rejected) drop out.
- */
-export function curateDiff(files: DiffFileContents[], rejections: HunkRejection[]): string {
-  const parts: string[] = [];
-
-  for (const file of files) {
-    const fileRejections = rejections.filter((rejection) => rejection.path === file.path);
-    const patch = curateFilePatch(file, fileRejections);
-
-    if (patch) parts.push(patch);
-  }
-
-  return parts.join("\n");
-}

package/src/index.ts

@@ -3,6 +3,7 @@ export { serveClient, type ServeHandle, type ServeOptions } from "./serve";
 export { App, type AppProps } from "./App";
 export {
   collaboratorAnnotations,
+  mergeFromShare,
   publishShare,
   pullShare,
   pushShare,

package/src/intent-dispatch.test.ts

@@ -11,6 +11,7 @@ import { SCHEMA_VERSION, type Annotation, type ReviewSession } from "@cueloop/sc
 import { createIntentDispatch, type IntentDispatchDeps } from "./intent-dispatch";
 import type { ControllerSnapshot, CurationItem, ReviewController } from "./session-controller";
 import type { DisplayBlock } from "./view-plan";
+import type { TreeRow } from "./tree-view";
 
 function block(text: string): DisplayBlock {
   return { type: "same", kind: "p", work: { kind: "p", text, lineStart: 0, lineEnd: 0 } };
@@ -56,7 +57,7 @@ const EMPTY_SNAPSHOT: ControllerSnapshot = {
   walk: null,
 };
 
-/** A controller where every verb is a mock; annotate returns undefined by default. */
+/** A controller where every primitive is a mock; annotate returns undefined by default. */
 function baseController(): ReviewController {
   return {
     readOnly: false,
@@ -83,6 +84,7 @@ function baseController(): ReviewController {
     restoreCuration: mock(),
     edit: mock(),
     annotate: mock(() => undefined),
+    reply: mock(() => undefined),
     annotatePrototype: mock(() => undefined),
     updateAnnotation: mock(),
     removeAnnotation: mock(),
@@ -93,8 +95,14 @@ function baseController(): ReviewController {
     walkLeave: mock(),
     submit: mock(),
     share: mock(),
+    treeRows: mock(() => []),
+    goToEntry: mock(),
+    branch: mock(),
+    labelTip: mock(),
+    fork: mock(),
+    forkAndShare: mock(),
     pullShared: mock(() => Promise.resolve()),
-    startSharePoll: mock(() => () => {}),
+    startShareSync: mock(() => () => {}),
     finishReview: mock(),
     dismissCompletion: mock(),
     optInAutoClose: mock(),
@@ -120,18 +128,20 @@ function makeDeps(overrides: Partial<IntentDispatchDeps> = {}): IntentDispatchDe
     terminalWidth: 120,
     focusedAnnotationId: undefined,
     selectedCurationId: undefined,
+    railTab: "review",
+    selectedEntryId: undefined,
     authorNames: {},
     quickActions: [],
     renameAuthor: mock(),
     liveInput: { current: "" },
     reviewWidthRef: { current: 34 },
-    planSheetRef: { current: null },
     setCursor: mock(),
     setInboxCursor: mock(),
     setMode: mock(),
     setReviewMode: mock(),
     setReviewWidth: mock(),
     setRailTab: mock(),
+    setSelectedEntryId: mock(),
     setFocusedAnnotationId: mock(),
     setSelectedCurationId: mock(),
     setPulsedAnnotationId: mock(),
@@ -544,3 +554,126 @@ describe("collaborator self-name", () => {
     expect(deps.setMode).toHaveBeenCalledWith({ type: "normal" });
   });
 });
+
+describe("tree intents", () => {
+  const rows: TreeRow[] = [
+    {
+      entryId: "e1",
+      depth: 0,
+      glyph: "◉",
+      text: "revision 1",
+      onPath: true,
+      tips: [],
+      isCurrentTip: false,
+    },
+    {
+      entryId: "e2",
+      depth: 0,
+      glyph: "·",
+      text: "comment",
+      onPath: true,
+      tips: ["main"],
+      isCurrentTip: false,
+    },
+    {
+      entryId: "e3",
+      depth: 1,
+      glyph: "·",
+      text: "comment",
+      onPath: false,
+      tips: ["alt"],
+      isCurrentTip: true,
+    },
+  ];
+
+  function treeDeps(overrides: Partial<IntentDispatchDeps> = {}): IntentDispatchDeps {
+    const deps = makeDeps({ railTab: "tree", ...overrides });
+
+    deps.controller.treeRows = mock(() => rows);
+
+    return deps;
+  }
+
+  test("toggleTree shows the Tree tab and hides it again", () => {
+    // Arrange
+    const shown = makeDeps({ railTab: "review" });
+    const hidden = makeDeps({ railTab: "tree" });
+
+    // Act
+    createIntentDispatch(shown)({ type: "toggleTree" });
+    createIntentDispatch(hidden)({ type: "toggleTree" });
+
+    // Assert
+    expect(shown.setRailTab).toHaveBeenCalledWith("tree");
+    expect(hidden.setRailTab).toHaveBeenCalledWith("review");
+  });
+
+  test("treeMove starts from the current tip and stays inside the rows", () => {
+    // Arrange
+    const fromTip = treeDeps();
+    const atTop = treeDeps({ selectedEntryId: "e1" });
+
+    // Act
+    createIntentDispatch(fromTip)({ type: "treeMove", direction: -1 });
+    createIntentDispatch(atTop)({ type: "treeMove", direction: -1 });
+
+    // Assert
+    expect(fromTip.setSelectedEntryId).toHaveBeenCalledWith("e2");
+    expect(atTop.setSelectedEntryId).toHaveBeenCalledWith("e1");
+  });
+
+  test("treeGo: the tip answers, a tip of another branch switches, an inner entry asks for a summary", () => {
+    // Arrange
+    const atTip = treeDeps({ selectedEntryId: "e3" });
+    const toTip = treeDeps({ selectedEntryId: "e2" });
+    const inner = treeDeps({ selectedEntryId: "e1" });
+
+    // Act
+    createIntentDispatch(atTip)({ type: "treeGo" });
+    createIntentDispatch(toTip)({ type: "treeGo" });
+    createIntentDispatch(inner)({ type: "treeGo" });
+
+    // Assert
+    expect(atTip.controller.setStatus).toHaveBeenCalledWith("already at the tip");
+    expect(toTip.controller.goToEntry).toHaveBeenCalledWith("e2");
+    expect(inner.setMode).toHaveBeenCalledWith({
+      type: "treePrompt",
+      ask: "navigate",
+      entryId: "e1",
+      text: "",
+    });
+  });
+
+  test("the prompts confirm into branch, label, and a move back with the typed summary", () => {
+    // Arrange
+    const branch = treeDeps({ mode: { type: "treePrompt", ask: "branch", text: "alt" } });
+    const label = treeDeps({ mode: { type: "treePrompt", ask: "label", text: "start" } });
+    const navigate = treeDeps({
+      mode: { type: "treePrompt", ask: "navigate", entryId: "e1", text: " too early " },
+    });
+
+    // Act
+    createIntentDispatch(branch)({ type: "confirmDialog" });
+    createIntentDispatch(label)({ type: "confirmDialog" });
+    createIntentDispatch(navigate)({ type: "confirmDialog" });
+
+    // Assert
+    expect(branch.controller.branch).toHaveBeenCalledWith("alt");
+    expect(label.controller.labelTip).toHaveBeenCalledWith("start");
+    expect(navigate.controller.goToEntry).toHaveBeenCalledWith("e1", "too early");
+    expect(navigate.setMode).toHaveBeenCalledWith({ type: "normal" });
+  });
+
+  test("treeFork and treeForkShare reach the controller", () => {
+    // Arrange
+    const deps = treeDeps();
+
+    // Act
+    createIntentDispatch(deps)({ type: "treeFork" });
+    createIntentDispatch(deps)({ type: "treeForkShare" });
+
+    // Assert
+    expect(deps.controller.fork).toHaveBeenCalledTimes(1);
+    expect(deps.controller.forkAndShare).toHaveBeenCalledTimes(1);
+  });
+});

package/src/intent-dispatch.ts

@@ -7,14 +7,15 @@
  * into React beyond the setters it is given.
  */
 
-import type { Dispatch, MutableRefObject, RefObject, SetStateAction } from "react";
+import type { Dispatch, MutableRefObject, 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 { TreeRow } from "./tree-view";
+import type { RailTab } from "./components/ReviewRail";
 import { quickActionBody, type QuickAction } from "./config";
-import type { PlanSheetHandle } from "./components/PlanSheet";
 import { VERDICTS } from "./components/ConfirmCard";
 import {
   REVIEW_RESIZE_STEP,
@@ -40,7 +41,11 @@ export type Mode =
   | { type: "submit"; verdict: VerdictKind; summary: string }
   | { type: "confirmDelete"; sessionId: string; title: string }
   | { type: "rename"; authorId: string; text: string }
-  | { type: "nameSelf"; text: string };
+  | { type: "nameSelf"; text: string }
+  | { type: "treePrompt"; ask: TreeAsk; entryId?: string; text: string };
+
+/** What a tree prompt asks for: a branch name, a checkpoint name, or the summary a move back leaves. */
+export type TreeAsk = "branch" | "label" | "navigate";
 
 /** The marked span for span mode and its quick-actions sub-mode; null otherwise. */
 export function activeSpanState(mode: Mode): SpanState | null {
@@ -88,6 +93,9 @@ export interface IntentDispatchDeps {
   focusedAnnotationId: string | undefined;
   /** The curation item selected in the rail, if any; the undo target when set. */
   selectedCurationId: string | undefined;
+  railTab: RailTab;
+  /** The tree row selected in the rail's Tree tab; the target of go. */
+  selectedEntryId: string | undefined;
   /** Planner-local author renames, for seeding the rename prompt. */
   authorNames: Record<string, string>;
   /** Marker-popover quick actions, in list order; picking one inserts a preset comment. */
@@ -97,14 +105,14 @@ export interface IntentDispatchDeps {
 
   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">>;
+  setRailTab: Dispatch<SetStateAction<RailTab>>;
+  setSelectedEntryId: Dispatch<SetStateAction<string | undefined>>;
   setFocusedAnnotationId: Dispatch<SetStateAction<string | undefined>>;
   setSelectedCurationId: Dispatch<SetStateAction<string | undefined>>;
   setPulsedAnnotationId: Dispatch<SetStateAction<string | null>>;
@@ -187,6 +195,7 @@ function handleConfirmDialog(
   if (mode.type === "confirmDelete") controller.deleteSession(mode.sessionId);
   else if (mode.type === "rename") deps.renameAuthor(mode.authorId, mode.text.trim());
   else if (mode.type === "nameSelf") controller.setSelfName(mode.text.trim());
+  else if (mode.type === "treePrompt") confirmTreePrompt(mode, deps);
   deps.setMode({ type: "normal" });
 }
 
@@ -307,24 +316,17 @@ function handleOpenCompose(intent: IntentOfType<"openCompose">, deps: IntentDisp
         text: "",
       });
   } else {
-    // a mouse drag leaves a native selection; it wins over the cursor block
-    const native = deps.planSheetRef.current?.readSelection() ?? null;
-
-    if (native) {
-      deps.setMode({ type: "compose", kind: intent.kind, ...native, text: "" });
-    } else {
-      const block = deps.display[deps.cursor];
-
-      if (block)
-        deps.setMode({
-          type: "compose",
-          kind: intent.kind,
-          displayIndex: deps.cursor,
-          start: 0,
-          end: displayText(block).length,
-          text: "",
-        });
-    }
+    const block = deps.display[deps.cursor];
+
+    if (block)
+      deps.setMode({
+        type: "compose",
+        kind: intent.kind,
+        displayIndex: deps.cursor,
+        start: 0,
+        end: displayText(block).length,
+        text: "",
+      });
   }
 }
 
@@ -429,7 +431,6 @@ function handleRemoveAnnotation(
 }
 
 function handleDeselect(_intent: IntentOfType<"deselect">, deps: IntentDispatchDeps): void {
-  deps.planSheetRef.current?.clearSelection();
   deps.setFocusedAnnotationId(undefined);
   deps.setPulsedAnnotationId(null);
 }
@@ -526,6 +527,66 @@ function handleResizeReviewPanel(
   deps.controller.saveReviewPanel({ width: next });
 }
 
+function confirmTreePrompt(
+  mode: Extract<Mode, { type: "treePrompt" }>,
+  deps: IntentDispatchDeps,
+): void {
+  if (mode.ask === "branch") deps.controller.branch(mode.text);
+  else if (mode.ask === "label") deps.controller.labelTip(mode.text);
+  else if (mode.entryId !== undefined) deps.controller.goToEntry(mode.entryId, mode.text.trim());
+}
+
+function handleToggleTree(_intent: IntentOfType<"toggleTree">, deps: IntentDispatchDeps): void {
+  deps.setRailTab(deps.railTab === "tree" ? "review" : "tree");
+}
+
+/** The tree rows in drawing order; the selection falls back to the current tip. */
+function selectedTreeIndex(deps: IntentDispatchDeps, rows: TreeRow[]): number {
+  const byId = rows.findIndex((row) => row.entryId === deps.selectedEntryId);
+
+  return byId === -1 ? rows.findIndex((row) => row.isCurrentTip) : byId;
+}
+
+function handleTreeMove(intent: IntentOfType<"treeMove">, deps: IntentDispatchDeps): void {
+  const rows = deps.controller.treeRows();
+
+  if (rows.length === 0) return;
+  const current = selectedTreeIndex(deps, rows);
+  const next = Math.min(rows.length - 1, Math.max(0, current + intent.direction));
+
+  deps.setSelectedEntryId(rows[next]!.entryId);
+}
+
+function handleTreeGo(_intent: IntentOfType<"treeGo">, deps: IntentDispatchDeps): void {
+  const rows = deps.controller.treeRows();
+  const row = rows[selectedTreeIndex(deps, rows)];
+
+  if (!row) return deps.controller.setStatus("select an entry in the tree first");
+  if (row.isCurrentTip) return deps.controller.setStatus("already at the tip");
+  // a switch needs no summary; a move back may leave one, so it asks
+  if (row.tips.length > 0) return deps.controller.goToEntry(row.entryId);
+  deps.setMode({ type: "treePrompt", ask: "navigate", entryId: row.entryId, text: "" });
+}
+
+function handleTreeBranch(_intent: IntentOfType<"treeBranch">, deps: IntentDispatchDeps): void {
+  deps.setMode({ type: "treePrompt", ask: "branch", text: "" });
+}
+
+function handleTreeLabel(_intent: IntentOfType<"treeLabel">, deps: IntentDispatchDeps): void {
+  deps.setMode({ type: "treePrompt", ask: "label", text: "" });
+}
+
+function handleTreeFork(_intent: IntentOfType<"treeFork">, deps: IntentDispatchDeps): void {
+  deps.controller.fork();
+}
+
+function handleTreeForkShare(
+  _intent: IntentOfType<"treeForkShare">,
+  deps: IntentDispatchDeps,
+): void {
+  deps.controller.forkAndShare();
+}
+
 type IntentHandlers = {
   [Kind in Intent["type"]]: (intent: IntentOfType<Kind>, deps: IntentDispatchDeps) => void;
 };
@@ -572,6 +633,13 @@ const intentHandlers: IntentHandlers = {
   dismissCompletion: handleDismissCompletion,
   cycleReviewPanel: handleCycleReviewPanel,
   resizeReviewPanel: handleResizeReviewPanel,
+  toggleTree: handleToggleTree,
+  treeMove: handleTreeMove,
+  treeGo: handleTreeGo,
+  treeBranch: handleTreeBranch,
+  treeLabel: handleTreeLabel,
+  treeFork: handleTreeFork,
+  treeForkShare: handleTreeForkShare,
 };
 
 function dispatchIntent<Kind extends Intent["type"]>(

package/src/key-bindings.test.ts

@@ -43,7 +43,7 @@ describe("grammar-layer resolution", () => {
 });
 
 describe("mode layers own their keys", () => {
-  test("span mode resolves the span verbs, not the grammar", () => {
+  test("span mode resolves the span primitives, not the grammar", () => {
     // Arrange
     const resolver = bindings({ spanMode: true });
 

package/src/keymap.test.ts

@@ -224,7 +224,7 @@ describe("plan normal mode", () => {
     });
   }
 
-  test("resolved sessions guard the mutating verbs", () => {
+  test("resolved sessions guard the mutating primitives", () => {
     // Arrange
     const resolvedState = state({ resolved: true });
 
@@ -386,9 +386,9 @@ describe("diff mode", () => {
     ["p", [{ type: "prevAnnotation" }]],
     ["backspace", [{ type: "removeAnnotation" }]],
     ["return", [{ type: "openSubmit" }]],
-    ["v", [{ type: "status", message: "plan-only verb - diff review uses c on a line" }]],
+    ["v", [{ type: "status", message: "plan-only primitive - diff review uses c on a line" }]],
     ["x", [{ type: "rejectChange" }]],
-    ["e", [{ type: "status", message: "plan-only verb - diff review uses c on a line" }]],
+    ["e", [{ type: "status", message: "plan-only primitive - diff review uses c on a line" }]],
     ["q", [{ type: "exit" }]],
   ];
 
@@ -514,7 +514,7 @@ describe("review panel controls", () => {
     expect(reduceKey(observer, key("]"))).toEqual([{ type: "resizeReviewPanel", direction: 1 }]);
   });
 
-  test("span mode still owns b as a span verb, not a panel cycle", () => {
+  test("span mode still owns b as a span primitive, not a panel cycle", () => {
     // Assert
     expect(reduceKey(state({ spanMode: true }), key("b"))).toEqual([
       { type: "spanKey", name: "b" },

package/src/keymap.ts

@@ -1,7 +1,7 @@
 /**
  * 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.
  */
@@ -49,7 +49,14 @@ export type Intent =
   | { type: "optInAutoClose" }
   | { type: "dismissCompletion" }
   | { type: "cycleReviewPanel" }
-  | { type: "resizeReviewPanel"; direction: -1 | 1 };
+  | { type: "resizeReviewPanel"; direction: -1 | 1 }
+  | { type: "toggleTree" }
+  | { type: "treeMove"; direction: -1 | 1 }
+  | { type: "treeGo" }
+  | { type: "treeBranch" }
+  | { type: "treeLabel" }
+  | { type: "treeFork" }
+  | { type: "treeForkShare" };
 
 export interface KeyInput {
   name: string;
@@ -63,7 +70,7 @@ export interface KeyState {
   keys: Record<string, string[]>;
   readOnly: boolean;
   /**
-   * Owner-only verbs a share collaborator lacks (undefined = owner, allowed).
+   * 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 verdict (there is no agent on a share).
    */
@@ -95,7 +102,7 @@ export interface KeyState {
   cursorAnnotatable: boolean;
 }
 
-/** Verbs that write session state; an observer never reaches their handlers. */
+/** Primitives that write session state; an observer never reaches their handlers. */
 const MUTATING_ACTIONS = new Set([
   "comment",
   "cut",
@@ -136,7 +143,7 @@ export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: strin
 
   if (state.readOnly && mutating) return status("observer - read-only");
 
-  // share is a session-level verb: it works from any view, owner 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");
 
@@ -305,7 +312,7 @@ function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
 
   if (shared) return shared;
   if (action === "span" || action === "edit") {
-    return status("plan-only verb - diff review uses c on a line");
+    return status("plan-only primitive - diff review uses c on a line");
   }
 
   return [];
@@ -356,7 +363,7 @@ function planGrammar(state: KeyState, action: string | undefined, name: string):
     // 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 share viewer only annotates,
+    // 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 [];