@cueloop/client 0.1.0-alpha.0 → 0.1.0-alpha.100

package/src/annotations/components/AnnotationCards.test.tsx

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { CommentRow } from "./AnnotationCards";
+import { DARK } from "../../appearance/theme";
+import { TooltipProvider } from "../../ui/components/Tooltip";
+import { locateText, settle } from "../../testing/test-support";
+
+test("submitted comment checks stay visible on hover and navigate to the reply", async () => {
+  let navigations = 0;
+  const setup = await testRender(
+    <TooltipProvider>
+      <CommentRow
+        annotation={{
+          id: "submitted",
+          kind: "comment",
+          body: "Explain the change",
+          anchor: { quote: "change", prefix: "", suffix: "", blockIndex: 0, start: 0, end: 6 },
+          createdAt: "2026-10-04",
+        }}
+        tokens={DARK}
+        action={{ label: "View reply", run: () => navigations++ }}
+      />
+    </TooltipProvider>,
+    { width: 60, height: 8 },
+  );
+
+  try {
+    await settle(setup);
+    const checks = locateText(setup, "✓✓");
+
+    await setup.mockMouse.moveTo(checks.column, checks.row);
+    await settle(setup);
+    expect(setup.captureCharFrame()).toContain("✓✓");
+    expect(setup.captureCharFrame()).toContain("View reply");
+    expect(setup.captureCharFrame()).not.toContain("↓");
+    await setup.mockMouse.click(checks.column, checks.row);
+    expect(navigations).toBe(1);
+  } finally {
+    setup.renderer.destroy();
+  }
+});

package/src/annotations/components/AnnotationCards.tsx

@@ -0,0 +1,364 @@
+/**
+ * The inline comment pieces every annotated surface renders: the composer (a
+ * textarea in a card row), the "/" actions-and-skills palette below it, the
+ * edge-segmented discussion card, and one comment row. The plan thread view
+ * and the diff sheet both draw their comments with these, so a discussion looks
+ * and behaves the same on prose and on code.
+ */
+
+import React, { useContext, useLayoutEffect, useRef, useState } from "react";
+import { usePaste } from "@opentui/react";
+import type {
+  BoxRenderable,
+  KeyBinding,
+  MouseEvent as TerminalMouseEvent,
+  TextareaRenderable,
+} from "@opentui/core";
+import type { Annotation } from "@cueloop/schema";
+import type { Theme } from "../../appearance/theme";
+import { useTooltip } from "../../ui/components/Tooltip";
+import { lighten } from "../annotation-palette";
+import { useFrameMeasure } from "../../ui/use-frame-measure";
+import { imagePlaceholder, looksLikeBinaryPaste } from "../../integrations/pasted-image";
+import { skillReferenceRanges, type SlashItem } from "../../keyboard/slash-palette";
+import { PaletteNamesContext } from "../../keyboard/skills";
+import { referenceStyleFor } from "../../ui/components/syntax-highlight";
+
+/* -------------------------------------------------------------- composer */
+
+// Option+Enter saves a comment; Ctrl+Enter may additionally invoke the agent.
+// Plain Enter breaks the line. Command+Enter belongs to the terminal.
+const COMPOSE_KEY_BINDINGS: KeyBinding[] = [
+  { name: "return", super: true, action: "submit" },
+  { name: "return", meta: true, action: "submit" },
+  { name: "return", ctrl: true, action: "submit" },
+  { name: "return", action: "newline" },
+  { name: "return", shift: true, action: "newline" },
+];
+
+export function composeRowCount(text: string, contentWidth: number): number {
+  const usableWidth = contentWidth > 0 ? contentWidth : Number.MAX_SAFE_INTEGER;
+  let visualRowCount = 0;
+
+  for (const line of text.split("\n")) {
+    visualRowCount += Math.max(1, Math.ceil(line.length / usableWidth));
+  }
+
+  // no cap: the card is the discussion, and folding is its containment
+  return Math.max(1, visualRowCount);
+}
+
+export function Composer({
+  seed,
+  glyph,
+  tokens,
+  onSave,
+  onReady,
+  onInput,
+  placeholder,
+  agentEnabled = false,
+}: {
+  seed: string;
+  glyph: string | null;
+  tokens: Theme;
+  onSave: (body: string) => void;
+  onReady: (readText: () => string) => void;
+  onInput: (text: string, caret: number) => void;
+  placeholder?: string;
+  agentEnabled?: boolean;
+}): React.ReactNode {
+  const editorRef = useRef<TextareaRenderable | null>(null);
+  const pastedImageCount = useRef(0);
+  const [rows, setRows] = useState(1);
+  // action and skill names whose "/name" references paint in the accent color
+  const referenceNames = useContext(PaletteNamesContext);
+
+  usePaste((event) => {
+    const editor = editorRef.current;
+
+    if (!editor || !editor.focused || !looksLikeBinaryPaste(event.bytes)) return;
+    event.preventDefault();
+    pastedImageCount.current += 1;
+    editor.editBuffer.insertText(imagePlaceholder(pastedImageCount.current));
+  });
+
+  const paintReferences = (editor: TextareaRenderable): void => {
+    const { styleId } = referenceStyleFor(tokens);
+
+    editor.editBuffer.clearAllHighlights();
+    for (const range of skillReferenceRanges(editor.plainText, referenceNames)) {
+      editor.editBuffer.addHighlightByCharRange({ ...range, styleId });
+    }
+  };
+
+  // synchronously at commit, before the next tty key is read: signalling readiness in a
+  // post-paint effect lets a fast burst race the mount, splitting input between the seed
+  // buffer and this textarea out of order (#365)
+  useLayoutEffect(() => {
+    const editor = editorRef.current;
+
+    if (!editor) return;
+    editor.cursorOffset = seed.length;
+    editor.editBuffer.setSyntaxStyle(referenceStyleFor(tokens).style);
+    paintReferences(editor);
+    setRows(composeRowCount(editor.plainText, editor.width));
+    onReady(() => editorRef.current?.plainText ?? "");
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <box style={{ flexDirection: "row" }}>
+      {glyph !== null ? (
+        <text selectable={false} fg={tokens.text} style={{ flexShrink: 0 }}>{`${glyph} `}</text>
+      ) : null}
+      <textarea
+        ref={editorRef}
+        focused
+        initialValue={seed}
+        placeholder={placeholder}
+        placeholderColor={tokens.textDim}
+        cursorStyle={{ style: "block", blinking: true }}
+        keyBindings={
+          agentEnabled
+            ? COMPOSE_KEY_BINDINGS.filter((binding) => !binding.super)
+            : COMPOSE_KEY_BINDINGS
+        }
+        onSubmit={() => onSave(editorRef.current?.plainText ?? "")}
+        onContentChange={() => {
+          const editor = editorRef.current;
+
+          if (!editor) return;
+          paintReferences(editor);
+          setRows(composeRowCount(editor.plainText, editor.width));
+          onInput(editor.plainText, editor.cursorOffset);
+        }}
+        style={{
+          height: rows,
+          flexGrow: 1,
+          backgroundColor: "transparent",
+          focusedBackgroundColor: "transparent",
+          textColor: tokens.text,
+          focusedTextColor: tokens.text,
+        }}
+      />
+    </box>
+  );
+}
+
+/* ---------------------------------------------------------- slash palette */
+
+function SlashList({
+  items,
+  selected,
+  tokens,
+}: {
+  items: SlashItem[];
+  selected: number;
+  tokens: Theme;
+}): React.ReactNode {
+  const WINDOW = 5;
+  const start = Math.max(0, Math.min(selected - 2, items.length - WINDOW));
+  const visible = items.slice(start, start + WINDOW);
+
+  if (items.length === 0) return <text fg={tokens.textDim}>no matching actions</text>;
+
+  const nameColumn = Math.min(36, Math.max(16, ...visible.map((item) => item.name.length + 5)));
+
+  return (
+    <box style={{ flexDirection: "column" }}>
+      {visible.map((item, offset) => {
+        const index = start + offset;
+        const isSelected = index === selected;
+        const name = `${isSelected ? "→ " : "  "}/${item.name}`.padEnd(nameColumn);
+
+        return (
+          <text key={item.name} style={{ flexShrink: 0, wrapMode: "none" }}>
+            <span fg={isSelected ? tokens.accent : tokens.textMuted}>{name}</span>
+            <span fg={tokens.textDim}>{item.description}</span>
+          </text>
+        );
+      })}
+      {items.length > WINDOW ? (
+        <text fg={tokens.textDim}>{`(${selected + 1}/${items.length})`}</text>
+      ) : null}
+    </box>
+  );
+}
+
+/** Below the composer: the actions/skills list while the caret is on a "/word", else nothing. */
+export function ComposerPalette({
+  slashActive,
+  slashItems,
+  slashIndex,
+  tokens,
+}: {
+  slashActive: boolean;
+  slashItems: SlashItem[];
+  slashIndex: number;
+  tokens: Theme;
+}): React.ReactNode {
+  if (!slashActive) return null;
+
+  return (
+    <box style={{ flexDirection: "column", marginLeft: 3 }}>
+      <SlashList
+        items={slashItems}
+        selected={Math.min(slashIndex, Math.max(0, slashItems.length - 1))}
+        tokens={tokens}
+      />
+    </box>
+  );
+}
+
+/* ------------------------------------------------------------ discussion card */
+
+/** One card row group with its own accent-edge color, one per voice. */
+export interface EdgeSegment {
+  color: string;
+  node: React.ReactNode;
+}
+
+/**
+ * The comment-card frame. The accent edge is drawn by hand so that (a) its
+ * corner cells are half-height glyphs ("╷"/"╵") terminating flush with the
+ * hairline rows, and (b) each voice's rows carry their own edge color with
+ * zero gap. Focus lightens every segment; the hairlines never change.
+ */
+export function DiscussionCard({
+  segments,
+  tokens,
+  focused = false,
+  onFocus,
+}: {
+  segments: EdgeSegment[];
+  tokens: Theme;
+  focused?: boolean;
+  onFocus?: () => void;
+}): React.ReactNode {
+  const segmentRefs = useRef<Array<BoxRenderable | null>>([]);
+  const noHeights: number[] = [];
+  const heights = useFrameMeasure(
+    () => segmentRefs.current.map((renderable) => renderable?.height ?? 0),
+    (left, right) => left.join() === right.join(),
+    noHeights,
+  );
+
+  const edgeColor = (color: string): string => (focused ? lighten(color) : color);
+  const glyphs = focused
+    ? { top: "╻", middle: "┃", bottom: "╹" }
+    : { top: "╷", middle: "│", bottom: "╵" };
+  const edgeRows: Array<{ glyph: string; color: string }> = [
+    {
+      glyph: glyphs.top,
+      color: edgeColor(segments[0]?.color ?? tokens.border),
+    },
+  ];
+
+  for (let index = 0; index < segments.length; index++) {
+    const segmentRows = Math.max(1, heights[index] ?? 1);
+
+    for (let row = 0; row < segmentRows; row++) {
+      edgeRows.push({
+        glyph: glyphs.middle,
+        color: edgeColor(segments[index]!.color),
+      });
+    }
+  }
+  edgeRows.push({
+    glyph: glyphs.bottom,
+    color: edgeColor(segments[segments.length - 1]?.color ?? tokens.border),
+  });
+
+  return (
+    <box style={{ flexDirection: "row", marginTop: 0, marginLeft: 2 }}>
+      <text selectable={false} style={{ flexShrink: 0, width: 1 }}>
+        {edgeRows.map((row, index) => (
+          <span key={index} fg={row.color}>
+            {index < edgeRows.length - 1 ? `${row.glyph}\n` : row.glyph}
+          </span>
+        ))}
+      </text>
+      <box
+        onMouseDown={onFocus}
+        style={{
+          flexGrow: 1,
+          flexDirection: "column",
+          border: ["top", "right", "bottom"],
+          borderStyle: "single",
+          borderColor: tokens.border,
+          backgroundColor: "transparent",
+          paddingLeft: 1,
+          paddingRight: 1,
+        }}
+      >
+        {segments.map((segment, index) => (
+          <box
+            key={index}
+            ref={(renderable: BoxRenderable | null) => {
+              segmentRefs.current[index] = renderable;
+            }}
+            style={{ flexDirection: "column" }}
+          >
+            {segment.node}
+          </box>
+        ))}
+      </box>
+    </box>
+  );
+}
+
+export function CommentRow({
+  annotation,
+  tokens,
+  authorLabel,
+  action,
+}: {
+  annotation: Annotation;
+  tokens: Theme;
+  /** The author's resolved display name, shown as a tooltip when the dot is hovered. */
+  authorLabel?: string;
+  action?: { label: string; run: () => void };
+}): React.ReactNode {
+  // own comments (no author) wear the filled dot, collaborators the outline
+  const own = annotation.author === undefined;
+  const glyph = own ? "●" : "○";
+  const glyphColor = annotation.orphan ? tokens.warning : own ? tokens.text : tokens.textMuted;
+  const { showTooltip, hideTooltip } = useTooltip();
+  const dotHover = authorLabel
+    ? {
+        onMouseOver: (event: TerminalMouseEvent) => showTooltip(authorLabel, event.x, event.y),
+        onMouseOut: hideTooltip,
+      }
+    : {};
+
+  return (
+    <box style={{ flexDirection: "column" }}>
+      {annotation.body.split("\n").map((line, lineIndex) => (
+        <box key={lineIndex} style={{ flexDirection: "row" }}>
+          <box style={{ flexShrink: 0 }} {...(lineIndex === 0 ? dotHover : {})}>
+            <text selectable={false} fg={glyphColor}>
+              {lineIndex === 0 ? `${glyph} ` : "  "}
+            </text>
+          </box>
+          <text fg={tokens.text} style={{ wrapMode: "word", flexGrow: 1, flexShrink: 1 }}>
+            {line}
+          </text>
+          {lineIndex === 0 && action ? (
+            <text
+              fg={tokens.blue}
+              onMouseUp={action.run}
+              onMouseOver={(event: TerminalMouseEvent) => {
+                showTooltip(action.label, event.x, event.y);
+              }}
+              onMouseOut={() => {
+                hideTooltip();
+              }}
+            >
+              {action.label === "Retry" ? "Retry" : "✓✓"}
+            </text>
+          ) : null}
+        </box>
+      ))}
+    </box>
+  );
+}

package/src/annotations/components/DiscussionMarkerRail.stories.tsx

@@ -0,0 +1,54 @@
+import React from "react";
+import type { Annotation } from "@cueloop/schema";
+import { DARK } from "../../appearance/theme";
+import type { Discussion } from "../discussions";
+import type { TextSpan } from "../thread-selection";
+import { RootOverlayProvider } from "../../ui/components/RootOverlay";
+import { DiscussionMarkerRail } from "./DiscussionMarkerRail";
+import type { Story, StoryMeta } from "../../stories/story";
+
+export const meta: StoryMeta = { title: "Chrome/DiscussionMarkerRail" };
+
+function comment(id: string, body: string): Annotation {
+  return {
+    id,
+    kind: "comment",
+    anchor: { quote: body, prefix: "", suffix: "" },
+    body,
+    createdAt: "2026-09-08T00:00:00.000Z",
+  };
+}
+
+function discussion(row: number, body: string): Discussion {
+  const span: TextSpan = { start: { blockIndex: row, char: 0 }, end: { blockIndex: row, char: 4 } };
+
+  return {
+    key: `${row}`,
+    rootId: `a${row}`,
+    blockIndex: row,
+    span,
+    annotations: [comment(`a${row}`, body)],
+  };
+}
+
+const discussions = [
+  discussion(2, "Map needs an eviction story."),
+  discussion(5, "why a Map here?"),
+  discussion(9, "name this constant"),
+];
+
+// The centered dot column: one dot per discussion, drawn on a surface's right edge.
+export const Dots: Story = {
+  render: () => (
+    <RootOverlayProvider>
+      <box
+        style={{ width: 24, height: 10, flexDirection: "row", backgroundColor: DARK.background }}
+      >
+        <box style={{ flexGrow: 1 }} />
+        <DiscussionMarkerRail discussions={discussions} spanQuote={() => "x"} onJump={() => {}} />
+      </box>
+    </RootOverlayProvider>
+  ),
+  expectedColors: [DARK.textDim],
+  size: { width: 24, height: 10 },
+};

package/src/annotations/components/DiscussionMarkerRail.tsx

@@ -0,0 +1,186 @@
+/**
+ * The right-edge discussion navigator: a vertically-centered column of dots, one
+ * per discussion, that highlights on hover, shows a floating preview, and jumps
+ * on click. The plan thread view and each diff editor group render one on their
+ * right edge, so comment navigation reads the same on prose and on code. The
+ * preview draws at the app root (OpenTUI has no z-index) so no pane border slices it.
+ */
+
+import React, { useEffect, useRef, useState, type RefObject } from "react";
+import type { BoxRenderable, ScrollBoxRenderable } from "@opentui/core";
+import type { Theme } from "../../appearance/theme";
+import type { TextSpan } from "../thread-selection";
+import type { Discussion } from "../discussions";
+import { useFrameMeasure } from "../../ui/use-frame-measure";
+import { useComponentTheme } from "../../appearance/components/theme-context";
+import { useRootOverlay } from "../../ui/components/RootOverlay";
+import { OverlayScrollbar } from "../../ui/components/OverlayScrollbar";
+
+interface HoveredMarker {
+  key: string;
+  screenY: number;
+  anchorX: number;
+}
+
+function ScrollMarkers({
+  discussions,
+  hovered,
+  focused,
+  tokens,
+  onHover,
+  onJump,
+}: {
+  discussions: Discussion[];
+  hovered: string | null;
+  focused: string | null;
+  tokens: Theme;
+  onHover: (marker: HoveredMarker | null) => void;
+  onJump: (key: string) => void;
+}): React.ReactNode {
+  const railRef = useRef<BoxRenderable | null>(null);
+  const height = useFrameMeasure(
+    () => railRef.current?.height ?? 0,
+    (left, right) => left === right,
+    0,
+  );
+
+  const firstRow = Math.max(0, Math.floor((height - discussions.length) / 2));
+  const rowFor = (index: number): number => firstRow + index;
+  const indexAt = (row: number): number | null => {
+    const index = row - firstRow;
+
+    return index >= 0 && index < discussions.length ? index : null;
+  };
+  const hoveredIndex = discussions.findIndex((discussion) => discussion.key === hovered);
+  const focusedIndex = discussions.findIndex((discussion) => discussion.key === focused);
+  const isActive = (index: number): boolean => index === hoveredIndex || index === focusedIndex;
+  const colorFor = (index: number): string => {
+    if (isActive(index)) return tokens.text;
+    if (hoveredIndex >= 0 && discussions.length >= 5 && Math.abs(index - hoveredIndex) === 1) {
+      return tokens.textMuted;
+    }
+
+    return tokens.textDim;
+  };
+
+  return (
+    <box
+      ref={railRef}
+      style={{ width: 3, flexShrink: 0, flexDirection: "column" }}
+      onMouseMove={(event) => {
+        const railY = railRef.current?.y ?? 0;
+        const index = indexAt(event.y - railY);
+
+        onHover(
+          index === null
+            ? null
+            : {
+                key: discussions[index]!.key,
+                // screen coordinates so the preview can render at the app root, above every pane rule
+                screenY: railY + rowFor(index),
+                anchorX: railRef.current?.x ?? 0,
+              },
+        );
+      }}
+      onMouseOut={() => onHover(null)}
+      onMouseDown={(event) => {
+        const index = indexAt(event.y - (railRef.current?.y ?? 0));
+
+        if (index !== null) onJump(discussions[index]!.key);
+      }}
+    >
+      {discussions.map((discussion, index) => (
+        <text
+          key={discussion.key}
+          selectable={false}
+          style={{ position: "absolute", top: rowFor(index), left: 0 }}
+          fg={colorFor(index)}
+        >
+          {(isActive(index) ? "●" : "○").padStart(2)}
+        </text>
+      ))}
+    </box>
+  );
+}
+
+export interface DiscussionMarkerRailProps {
+  discussions: Discussion[];
+  spanQuote: (span: TextSpan) => string;
+  focusedKey?: string | null;
+  onJump: (key: string) => void;
+  scrollbox?: RefObject<ScrollBoxRenderable | null>;
+  theme?: Theme;
+}
+
+export function DiscussionMarkerRail({
+  discussions,
+  spanQuote,
+  focusedKey = null,
+  onJump,
+  scrollbox,
+  theme,
+}: DiscussionMarkerRailProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const [hovered, setHovered] = useState<HoveredMarker | null>(null);
+  const { setOverlay, clearOverlay } = useRootOverlay();
+
+  const preview = (): React.ReactNode => {
+    if (hovered === null) return null;
+    const discussion = discussions.find((candidate) => candidate.key === hovered.key);
+
+    if (!discussion) return null;
+    const quote = spanQuote(discussion.span);
+    const lastComment = discussion.annotations.at(-1)!;
+
+    return (
+      <box
+        style={{
+          position: "absolute",
+          top: Math.max(0, hovered.screenY - 1),
+          left: Math.max(0, hovered.anchorX - 48),
+          width: 48,
+          flexDirection: "column",
+          border: true,
+          borderStyle: "single",
+          borderColor: tokens.border,
+          backgroundColor: tokens.elevated,
+          paddingLeft: 1,
+          paddingRight: 1,
+        }}
+      >
+        <text fg={tokens.textDim}>{`"${quote.slice(0, 42)}"`}</text>
+        <text fg={tokens.text}>
+          {`${lastComment.author === undefined ? "●" : "○"} ${lastComment.body}`.slice(0, 44)}
+        </text>
+        <text fg={tokens.textDim}>
+          {`${discussion.annotations.length} comment${
+            discussion.annotations.length === 1 ? "" : "s"
+          } · click to jump`}
+        </text>
+      </box>
+    );
+  };
+
+  // render the preview at the app root (above every pane rule); OpenTUI has no z-index, so an
+  // absolute box inside this pane would be sliced by the next pane's border
+  useEffect(() => {
+    setOverlay("discussion-preview", preview());
+
+    return () => clearOverlay("discussion-preview");
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hovered, discussions, tokens]);
+
+  return (
+    <>
+      <ScrollMarkers
+        discussions={discussions}
+        hovered={hovered?.key ?? null}
+        focused={focusedKey}
+        tokens={tokens}
+        onHover={setHovered}
+        onJump={onJump}
+      />
+      {scrollbox ? <OverlayScrollbar scrollbox={scrollbox} theme={theme} /> : null}
+    </>
+  );
+}