@cueloop/client 0.1.0-alpha.77 → 0.1.0-alpha.79

package/src/use-annotation-surface.tsx

@@ -37,9 +37,9 @@ import {
 } from "./thread-selection";
 import { annotationPaletteFor, type AnnotationPalette } from "./annotation-palette";
 import { printableSequence, type MarkRange, type VisualLine } from "./mark-runs";
-import { matchesLeader } from "./thread-chords";
 import {
   activeSlashToken,
+  insertSlashItem,
   isStandaloneSlashQuery,
   mergeSlashItems,
   slashFilter,
@@ -106,8 +106,8 @@ export interface AnnotationSurfaceOptions {
   onUpdateAnnotation: (id: string, body: string) => void;
   /** The author's display name for a comment's hover tooltip; the rail resolves it against the participant registry. */
   resolveAuthorLabel?: (annotation: Annotation) => string | undefined;
-  leaderCombos?: readonly string[];
-  onLeaderCommand?: (key: KeyEvent) => void;
+  /** Resolve a nav-mode key to a session/curation/tree/diff command; true when it acted. */
+  onNavCommand?: (key: KeyEvent) => boolean;
   onExit: () => void;
 }
 
@@ -118,6 +118,8 @@ export interface AnnotationSurface {
   cursor: number;
   head: TextPosition;
   compose: ComposeState | null;
+  /** True while the surface is in nav mode: bare keys act as commands, typing does not compose. */
+  navMode: boolean;
   focusedDiscussion: string | null;
   /** The block to keep in view: an opening card, a focused discussion, else the caret. */
   revealBlockIndex: number;
@@ -182,8 +184,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     onReply,
     onUpdateAnnotation,
     resolveAuthorLabel,
-    leaderCombos,
-    onLeaderCommand,
+    onNavCommand,
     onExit,
   } = options;
   const palette = annotationPaletteFor(tokens);
@@ -198,7 +199,12 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     return { head: start, anchor: start };
   });
   const [compose, setCompose] = useState<ComposeState | null>(null);
-  const leaderPending = useRef(false);
+  const [navMode, setNavModeState] = useState(false);
+  const navModeRef = useRef(false);
+  const setNavMode = (value: boolean): void => {
+    navModeRef.current = value;
+    setNavModeState(value);
+  };
 
   useEffect(() => {
     onComposingChange?.(compose !== null);
@@ -243,6 +249,11 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
   };
   const [folded, setFolded] = useState<Set<string>>(new Set());
   const [composeText, setComposeText] = useState("");
+  const composeTextRef = useRef("");
+  const setDraft = (text: string): void => {
+    composeTextRef.current = text;
+    setComposeText(text);
+  };
   const [caretOffset, setCaretOffset] = useState(0);
   const [slashIndex, setSlashIndex] = useState(0);
   const composerReady = useRef(false);
@@ -314,14 +325,14 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     composerReady.current = false;
     composeRef.current = state;
     setCompose(state);
-    setComposeText(state.seed);
+    setDraft(state.seed);
     setCaretOffset(state.seed.length);
     setSlashIndex(0);
   };
   const closeCompose = (): void => {
     composeRef.current = null;
     setCompose(null);
-    setComposeText("");
+    setDraft("");
     setCaretOffset(0);
   };
   const skills = useContext(SlashSkillsContext);
@@ -451,14 +462,10 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
       return true;
     }
     if (key.name === "return" || key.name === "tab") {
-      const token = activeSlashToken(composeText, caretOffset) ?? "";
-      const cut = caretOffset - token.length;
-      const insertion = `/${slashItems[selected]!.name} `;
-      const seed = composeText.slice(0, cut) + insertion + composeText.slice(caretOffset);
+      const inserted = insertSlashItem(composeText, caretOffset, slashItems[selected]!.name);
 
-      openCompose({ ...activeCompose, seed });
-      // land the caret just after the inserted reference, not at the end of a chained draft
-      setCaretOffset(cut + insertion.length);
+      openCompose({ ...activeCompose, seed: inserted.text });
+      setCaretOffset(inserted.caret);
 
       return true;
     }
@@ -473,7 +480,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
       const grown = { ...activeCompose, seed: `${activeCompose.seed}\n` };
 
       composeRef.current = grown;
-      setComposeText(grown.seed);
+      setDraft(grown.seed);
       setCaretOffset(grown.seed.length);
 
       return setCompose(grown);
@@ -484,7 +491,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
       const grown = { ...activeCompose, seed: activeCompose.seed + sequence };
 
       composeRef.current = grown;
-      setComposeText(grown.seed);
+      setDraft(grown.seed);
       setCaretOffset(grown.seed.length);
       setCompose(grown);
     }
@@ -503,7 +510,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     // (an edit of an existing comment is never deleted this way)
     if (
       key.name === "backspace" &&
-      composeText.length === 0 &&
+      composeTextRef.current.length === 0 &&
       activeCompose.editAnnotationId === null
     ) {
       return closeCompose();
@@ -512,7 +519,22 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     if (!composerReady.current) handlePremountKey(key, activeCompose);
   };
 
-  /** m / cmd+[ / cmd+] / tab / return - true when the key was a discussion primitive. */
+  /** Fold or unfold every discussion sitting on the caret's block (nav-mode z). */
+  const toggleFoldAtCursor = (): void => {
+    setFolded((current) => {
+      const next = new Set(current);
+
+      for (const discussion of discussions) {
+        if (discussion.blockIndex !== cursor) continue;
+        if (next.has(discussion.key)) next.delete(discussion.key);
+        else next.add(discussion.key);
+      }
+
+      return next;
+    });
+  };
+
+  /** m / cmd+[ / cmd+] / return - true when the key was a discussion primitive. */
   const handleDiscussionVerb = (key: KeyEvent): boolean => {
     // comment on selection: cmd+option+m (alt+m where cmd arrives ESC-prefixed)
     if (key.name === "m" && (key.super || key.meta || key.option)) {
@@ -536,21 +558,6 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
 
       return true;
     }
-    if (key.name === "tab") {
-      setFolded((current) => {
-        const next = new Set(current);
-
-        for (const discussion of discussions) {
-          if (discussion.blockIndex !== cursor) continue;
-          if (next.has(discussion.key)) next.delete(discussion.key);
-          else next.add(discussion.key);
-        }
-
-        return next;
-      });
-
-      return true;
-    }
     // enter replies into the focused discussion, else the cursor block's discussion
     if (key.name === "return") {
       const replyTarget =
@@ -666,23 +673,25 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
 
     if (activeCompose) return handleComposeKey(key, activeCompose);
     if (key.name === "escape") {
-      if (leaderPending.current) {
-        leaderPending.current = false;
-
-        return;
-      }
-      if (focusedDiscussion !== null) return setFocusedDiscussion(null);
+      // from type mode esc only enters nav, so a held mark survives for `c`
+      if (!navModeRef.current) return setNavMode(true);
+      if (focusedDiscussion !== null) setFocusedDiscussion(null);
 
       return collapseCaret();
     }
-    if (leaderPending.current) {
-      leaderPending.current = false;
-      onLeaderCommand?.(key);
-
-      return;
-    }
-    if (leaderCombos && matchesLeader(key, leaderCombos)) {
-      leaderPending.current = true;
+    if (navModeRef.current) {
+      if (handleCaretKey(key)) return;
+      if (key.name === "z") return toggleFoldAtCursor();
+      if (onNavCommand?.(key)) return;
+      if (key.name === "c") {
+        setNavMode(false);
+
+        return openNewCompose("");
+      }
+      if (printableSequence(key)) {
+        setNavMode(false);
+        startTyping(key);
+      }
 
       return;
     }
@@ -704,7 +713,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
       onSave={saveComment}
       onReady={() => (composerReady.current = true)}
       onInput={(text, caret) => {
-        setComposeText(text);
+        setDraft(text);
         setCaretOffset(caret);
       }}
     />
@@ -799,9 +808,36 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     const endsInLine = (end: number): boolean => end - 1 >= line.start && end - 1 < line.end;
     const nodes: React.ReactNode[] = [];
     const composeHere = compose && compose.blockIndex === blockIndex;
+    const newComposeHere = Boolean(composeHere && compose.discussionKey === null && composerNode);
+    const composeAnchoredHere =
+      newComposeHere && (compose!.span ? endsInLine(compose!.span.end.char) : isLastLine);
+    const composeStart = compose?.span?.start;
+
+    const pushComposeCard = (): void => {
+      nodes.push(
+        <DiscussionCard
+          key="compose-new"
+          tokens={tokens}
+          segments={[{ color: palette.cardEdge, node: composerNode }]}
+        />,
+      );
+      nodes.push(paletteNode);
+    };
+
+    // the draft sorts in by its span start, the same order discussionsFrom lands it on save, so a
+    // new comment sits in its final position while typing instead of appending to the stack
+    let composePending = composeAnchoredHere;
 
     for (const discussion of discussions) {
       if (discussion.blockIndex !== blockIndex || !endsInLine(discussion.span.end.char)) continue;
+      if (
+        composePending &&
+        composeStart &&
+        comparePositions(composeStart, discussion.span.start) < 0
+      ) {
+        pushComposeCard();
+        composePending = false;
+      }
       const composingHere = Boolean(composeHere && compose.discussionKey === discussion.key);
 
       if (folded.has(discussion.key) && !composingHere) {
@@ -811,20 +847,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
       nodes.push(discussionCardFor(discussion, composingHere));
       if (composingHere) nodes.push(paletteNode);
     }
-    if (composeHere && compose.discussionKey === null && composerNode) {
-      const anchoredHere = compose.span ? endsInLine(compose.span.end.char) : isLastLine;
-
-      if (anchoredHere) {
-        nodes.push(
-          <DiscussionCard
-            key="compose-new"
-            tokens={tokens}
-            segments={[{ color: palette.cardEdge, node: composerNode }]}
-          />,
-        );
-        nodes.push(paletteNode);
-      }
-    }
+    if (composePending) pushComposeCard();
 
     return nodes;
   };
@@ -849,6 +872,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     const pressed = positionAt(allGeometry(), event.x, event.y);
 
     if (!pressed || !source.annotatable(pressed.blockIndex)) return;
+    setNavMode(false);
     const stamp = { time: Date.now(), x: event.x, y: event.y };
     const wordMode = isDoubleClick(lastClick.current, stamp);
 
@@ -876,6 +900,7 @@ export function useAnnotationSurface(options: AnnotationSurfaceOptions): Annotat
     cursor,
     head,
     compose,
+    navMode,
     focusedDiscussion,
     revealBlockIndex,
     spanQuote,

package/src/use-settings-dialog.tsx

@@ -35,11 +35,14 @@ export interface SettingsDialogModel {
   cycleSetting: (rowKey: string) => void;
   handleSettingsKey: (name: string) => void;
   onCategorySelect: (categoryId: string) => void;
+  /** Open the settings dialog focused on the left nav, from a fresh state. */
+  openSettings: () => void;
 }
 
 const DOWN_KEYS = new Set(["j", "down"]);
 const UP_KEYS = new Set(["k", "up"]);
-const ENTER_BODY_KEYS = new Set(["l", "tab", "return"]);
+const ENTER_BODY_KEYS = new Set(["l", "right", "tab", "return"]);
+const BACK_TO_NAV_KEYS = new Set(["h", "left", "tab"]);
 const ACTIVATE_KEYS = new Set(["return", "space", "l"]);
 
 function moveNavZone(
@@ -64,7 +67,7 @@ function moveNavZone(
 function moveBodyRow(name: string, nav: SettingsNav, rowCount: number): SettingsNav | null {
   if (DOWN_KEYS.has(name)) return { ...nav, rowIndex: Math.min(rowCount - 1, nav.rowIndex + 1) };
   if (UP_KEYS.has(name)) return { ...nav, rowIndex: Math.max(0, nav.rowIndex - 1) };
-  if (name === "h" || name === "tab") return { ...nav, zone: "nav" };
+  if (BACK_TO_NAV_KEYS.has(name)) return { ...nav, zone: "nav" };
 
   return null;
 }
@@ -108,10 +111,11 @@ export function useSettingsDialog(params: {
     onRenameDisplayName,
   } = params;
 
+  // open focused on the left nav, so up/down browses categories until l/tab/enter enters the body
   const [settingsNav, setSettingsNav] = useState<SettingsNav>({
     categoryId: "general",
     rowIndex: 0,
-    zone: "body",
+    zone: "nav",
   });
   const [actionsExpandedIndex, setActionsExpandedIndex] = useState<number | null>(null);
   const [actionsExpandedField, setActionsExpandedField] = useState<"prompt" | "metadata">("prompt");
@@ -247,6 +251,12 @@ export function useSettingsDialog(params: {
     }
   };
 
+  const openSettings = (): void => {
+    setSettingsNav({ categoryId: "general", rowIndex: 0, zone: "nav" });
+    setActionsExpandedIndex(null);
+    setMenuDialog("settings");
+  };
+
   const onCategorySelect = (categoryId: string): void => {
     // ignore a select that names no real category, so the key handler never dereferences nothing
     if (!settingsCategories.some((category) => category.id === categoryId)) return;
@@ -305,5 +315,6 @@ export function useSettingsDialog(params: {
     cycleSetting,
     handleSettingsKey,
     onCategorySelect,
+    openSettings,
   };
 }

package/src/use-thread-body-editing.tsx

@@ -0,0 +1,58 @@
+/**
+ * The thread pane's inline edit mode: owns whether the native markdown editor is
+ * open over the body, the editor element itself, and the open and exit handles.
+ * Opening is gated to an editable thread (the caller passes canEdit - owner,
+ * unresolved, not a diff); exiting saves the edited body as the working copy
+ * through the controller, so leaving the editor never loses work. The header
+ * edit/normal toggle exits through requestExit; switching threads closes the
+ * editor. Rendering the editor lives here too, so the pane pulls in one concept
+ * rather than wiring the component and its handle ref by hand.
+ */
+
+import React, { useRef, useState } from "react";
+import type { Theme } from "./theme";
+import type { ReviewController } from "./thread-controller";
+import { MarkdownThreadEditor, type MarkdownEditorHandle } from "./components/MarkdownThreadEditor";
+
+export interface ThreadBodyEditing {
+  /** True while the inline markdown editor owns the thread pane and its keys. */
+  editing: boolean;
+  /** Open the editor when the active thread is editable; a no-op otherwise. */
+  openEditor: () => void;
+  /** Save the current text and close - the header edit/normal toggle's exit. */
+  requestExit: () => void;
+  /** The editor element for the thread pane, bound to the working copy and theme. */
+  renderEditor: (theme: Theme) => React.ReactNode;
+}
+
+export function useThreadBodyEditing(options: {
+  controller: ReviewController;
+  sessionId: string | undefined;
+  canEdit: boolean;
+}): ThreadBodyEditing {
+  const { controller, sessionId, canEdit } = options;
+  // key editing by thread id so a thread switch closes the editor with no effect or ref
+  const [editingSessionId, setEditingSessionId] = useState<string | null>(null);
+  const handleRef = useRef<MarkdownEditorHandle | null>(null);
+  const editing = editingSessionId !== null && editingSessionId === sessionId;
+  const exitEditor = (text: string): void => {
+    controller.saveEditedBody(text);
+    setEditingSessionId(null);
+  };
+
+  return {
+    editing,
+    openEditor: () => {
+      if (canEdit && sessionId !== undefined) setEditingSessionId(sessionId);
+    },
+    requestExit: () => handleRef.current?.requestExit(),
+    renderEditor: (theme) => (
+      <MarkdownThreadEditor
+        ref={handleRef}
+        initialText={controller.working()}
+        theme={theme}
+        onExitEditor={exitEditor}
+      />
+    ),
+  };
+}

package/src/view-plan.test.ts

@@ -9,10 +9,14 @@ import {
   renderedOffsetAtOrAfter,
   renderedOffsetAtOrBefore,
   renderedOffsetFor,
+  renderedSpanToWork,
+  renderedStyleRuns,
+  renderedText,
   safeLinkHref,
   spanFromRange,
   spanKey,
   startSpan,
+  styledRunsFor,
   workRangeForRendered,
 } from "./view-plan";
 import { cutBlock, parseBlocks, restoreBlock, restoreLine, type Annotation } from "@cueloop/schema";
@@ -273,9 +277,9 @@ describe("rendered/work offset mapping", () => {
     const rendered = renderedOffsetFor(runs, wordsAt)!;
 
     // Assert
-    const renderedText = runs.map((run) => run.text).join("");
+    const renderedString = runs.map((run) => run.text).join("");
 
-    expect(renderedText.slice(rendered, rendered + "words".length)).toBe("words");
+    expect(renderedString.slice(rendered, rendered + "words".length)).toBe("words");
     // reading a rendered selection over "words" recovers the work range
     expect(workRangeForRendered(runs, rendered, rendered + "words".length)).toEqual({
       start: wordsAt,
@@ -287,11 +291,11 @@ describe("rendered/work offset mapping", () => {
     // Arrange
     const block = buildDisplay("old words\n", "new words\n")[0]!;
     const runs = blockRuns(block, true);
-    const renderedText = runs.map((run) => run.text).join("");
+    const renderedString = runs.map((run) => run.text).join("");
 
     // Act
     // select everything rendered: the work range is the whole work text
-    const range = workRangeForRendered(runs, 0, renderedText.length)!;
+    const range = workRangeForRendered(runs, 0, renderedString.length)!;
 
     // Assert
     expect(displayText(block).slice(range.start, range.end)).toBe(displayText(block));
@@ -319,9 +323,9 @@ describe("rendered/work offset mapping", () => {
     const renderedEnd = renderedOffsetAtOrBefore(runs, spanEnd - 1)!;
 
     // Assert
-    const renderedText = runs.map((run) => run.text).join("");
+    const renderedString = runs.map((run) => run.text).join("");
 
-    expect(renderedText.slice(renderedStart, renderedEnd + 1)).toBe("very");
+    expect(renderedString.slice(renderedStart, renderedEnd + 1)).toBe("very");
     // exact hits behave like renderedOffsetFor
     expect(renderedOffsetAtOrAfter(runs, 0)).toBe(0);
     expect(renderedOffsetAtOrBefore(runs, 0)).toBe(0);
@@ -404,3 +408,49 @@ describe("cut / restore round-trip", () => {
     expect(buildDisplay(BASE, restored).every((block) => block.type === "same")).toBe(true);
   });
 });
+
+describe("rendered-text projection (markers concealed)", () => {
+  const linkedBlock = () => buildDisplay("Use the `flag` and see [docs](https://x.dev).")[0]!;
+
+  test("renderedText drops inline markers, keeping visible characters", () => {
+    expect(renderedText(linkedBlock())).toBe("Use the flag and see docs.");
+  });
+
+  test("renderedText leaves a table block's source verbatim", () => {
+    const table = buildDisplay("| a | b |\n| --- | --- |\n| 1 | 2 |")[0]!;
+
+    expect(table.kind).toBe("table");
+    expect(renderedText(table)).toBe("| a | b |\n| --- | --- |\n| 1 | 2 |");
+  });
+
+  test("renderedSpanToWork maps a rendered link label back to its work offsets", () => {
+    const display = buildDisplay("Use the `flag` and see [docs](https://x.dev).");
+    // "docs" sits at rendered offset 21 ("Use the flag and see ".length)
+    const work = renderedSpanToWork(display, 0, 0, 21, 25);
+    const workText = display[0]!.work!.text;
+
+    expect(workText.slice(work.start, work.end)).toBe("docs");
+  });
+
+  test("renderedSpanToWork maps rendered inline code back to the backtick content", () => {
+    const display = buildDisplay("Use the `flag` and see docs.");
+    // "flag" sits at rendered offset 8 ("Use the ".length)
+    const work = renderedSpanToWork(display, 0, 0, 8, 12);
+
+    expect(display[0]!.work!.text.slice(work.start, work.end)).toBe("flag");
+  });
+
+  test("styledRunsFor colors a link run and marks the covered stretch", () => {
+    const linkRow = buildDisplay("see [docs](https://x.dev) now")[0]!;
+    const roleRuns = renderedStyleRuns(linkRow);
+    // "see docs now"; mark the whole "docs" label (rendered offsets 4..8)
+    const runs = styledRunsFor(roleRuns, { start: 0, end: renderedText(linkRow).length }, [
+      { start: 4, end: 8 },
+    ]);
+    const link = runs.find((run) => run.role === "link")!;
+
+    expect(link.text).toBe("docs");
+    expect(link.marked).toBe(true);
+    expect(runs.find((run) => run.text === "see ")!.marked).toBe(false);
+  });
+});