@cueloop/client 0.1.0-alpha.11 → 0.1.0-alpha.12

package/src/components/PlanSheet.tsx

@@ -0,0 +1,309 @@
+/**
+ * The plan document sheet: header chrome, the reconciliation banner, and the
+ * scrollable block flow. Each prose block renders as one natively wrapped
+ * text (wrapMode "word") beside a marker gutter, so wrapping is the
+ * renderer's job; the sheet keeps the rendered/work offset mapping per block
+ * and exposes an imperative selection surface - the keyboard span drives the
+ * native selection, and a mouse drag reads back as an exact work-text range,
+ * which keeps quote anchors char-precise.
+ */
+
+import React, { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { useRenderer } from "@opentui/react";
+import type { ScrollBoxRenderable, TextRenderable } from "@opentui/core";
+import type { ReviewSession } from "@cueloop/schema";
+import {
+  blockRuns,
+  displayText,
+  overlayMarks,
+  renderedOffsetFor,
+  revisionDelta,
+  workRangeForRendered,
+  type DisplayBlock,
+  type Mark,
+  type SpanState,
+  type StyleRun,
+} from "../view";
+import type { Theme } from "../theme";
+import { useComponentTheme } from "./theme-context";
+import { CodeBlock } from "./CodeBlock";
+import { AnnotationCard, type AnnotationDraft } from "./AnnotationCard";
+import { Button } from "./primitives/Button";
+import { Toolbar } from "./primitives/Toolbar";
+
+export interface PlanSelection {
+  dispIdx: number;
+  start: number;
+  end: number;
+}
+
+export interface PlanSheetHandle {
+  /** Work-text range of the current native (mouse) selection, if any. */
+  readSelection(): PlanSelection | null;
+  /** Anchor/extend the renderer's native selection from keyboard span offsets. */
+  driveSpanSelection(span: SpanState): void;
+  clearSelection(): void;
+  revealBlock(dispIdx: number): void;
+}
+
+export interface PlanComposeState {
+  kind: "comment" | "suggestion";
+  dispIdx: number;
+  quote: string;
+  draft: AnnotationDraft;
+}
+
+export interface PlanSheetProps {
+  session: ReviewSession;
+  display: DisplayBlock[];
+  marks: Map<number, Mark[]>;
+  cursor: number;
+  /** Extra selection-style paint on one block (keyboard span or compose anchor). */
+  activeSpan: { dispIdx: number; start: number; end: number } | null;
+  compose: PlanComposeState | null;
+  editOrphanCount: number;
+  onLineActivate: (dispIdx: number) => void;
+  onEditRequest: () => void;
+  theme?: Theme;
+}
+
+interface BlockRef {
+  renderable: TextRenderable;
+  runs: StyleRun[];
+}
+
+/** Screen position of a rendered-text offset inside a wrapped text. */
+function positionOfRenderedOffset(renderable: TextRenderable, renderedOffset: number): { x: number; y: number } {
+  const info = renderable.lineInfo;
+  let lineIndex = 0;
+  for (let index = 0; index < info.lineStartCols.length; index++) {
+    if (info.lineStartCols[index]! <= renderedOffset) lineIndex = index;
+    else break;
+  }
+  return {
+    x: renderable.x + renderedOffset - (info.lineStartCols[lineIndex] ?? 0),
+    y: renderable.y + lineIndex,
+  };
+}
+
+export const PlanSheet = forwardRef<PlanSheetHandle, PlanSheetProps>(function PlanSheet(
+  {
+    session,
+    display,
+    marks,
+    cursor,
+    activeSpan,
+    compose,
+    editOrphanCount,
+    onLineActivate,
+    onEditRequest,
+    theme,
+  }: PlanSheetProps,
+  handleRef,
+): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const renderer = useRenderer();
+  const blockRefs = useRef(new Map<number, BlockRef>());
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+
+  useImperativeHandle(handleRef, () => ({
+    readSelection: (): PlanSelection | null => {
+      if (!renderer?.hasSelection) return null;
+      const ordered = [...blockRefs.current.entries()].sort(([a], [b]) => a - b);
+      for (const [dispIdx, blockRef] of ordered) {
+        const selection = blockRef.renderable.getSelection();
+        if (!selection || selection.end <= selection.start) continue;
+        const range = workRangeForRendered(blockRef.runs, selection.start, selection.end);
+        if (range) return { dispIdx, ...range };
+      }
+      return null;
+    },
+    driveSpanSelection: (span: SpanState): void => {
+      if (!renderer) return;
+      const blockRef = blockRefs.current.get(span.dispIdx);
+      if (!blockRef) return;
+      const renderedStart = renderedOffsetFor(blockRef.runs, span.start);
+      const renderedEnd = renderedOffsetFor(blockRef.runs, span.end - 1);
+      if (renderedStart === null || renderedEnd === null) return;
+      const startPosition = positionOfRenderedOffset(blockRef.renderable, renderedStart);
+      const endPosition = positionOfRenderedOffset(blockRef.renderable, renderedEnd);
+      renderer.startSelection(blockRef.renderable, startPosition.x, startPosition.y);
+      renderer.updateSelection(blockRef.renderable, endPosition.x + 1, endPosition.y);
+    },
+    clearSelection: (): void => {
+      renderer?.clearSelection();
+    },
+    revealBlock: (dispIdx: number): void => {
+      try {
+        scrollRef.current?.scrollChildIntoView(`plan-block-${dispIdx}`);
+      } catch {
+        // reveal is best-effort; selection state is already correct
+      }
+    },
+  }));
+
+  const registerBlock = (dispIdx: number, renderable: TextRenderable | null, runs: StyleRun[]): void => {
+    if (renderable) blockRefs.current.set(dispIdx, { renderable, runs });
+    else blockRefs.current.delete(dispIdx);
+  };
+  // stale refs must not survive a shrinking display list
+  useEffect(() => {
+    for (const dispIdx of blockRefs.current.keys()) {
+      if (dispIdx >= display.length) blockRefs.current.delete(dispIdx);
+    }
+  }, [display]);
+
+  const children: React.ReactNode[] = [];
+  for (let dispIdx = 0; dispIdx < display.length; dispIdx++) {
+    const block = display[dispIdx]!;
+    const isCursor = dispIdx === cursor;
+    const gap = topGap(display[dispIdx - 1], block);
+    if (block.kind === "code") {
+      children.push(
+        <CodeBlock
+          key={dispIdx}
+          id={`plan-block-${dispIdx}`}
+          language={(block.work ?? block.base)?.lang}
+          content={displayText(block)}
+          isCursor={isCursor}
+          marginTop={gap}
+          isAnnotated={(marks.get(dispIdx) ?? []).length > 0}
+          changeTag={block.type !== "same" ? tagLabel(block) : undefined}
+          theme={theme}
+        />,
+      );
+    } else {
+      const blockMarks = [...(marks.get(dispIdx) ?? [])];
+      if (activeSpan && activeSpan.dispIdx === dispIdx) {
+        blockMarks.push({ start: activeSpan.start, end: activeSpan.end, role: "kspan" });
+      }
+      const runs = overlayMarks(blockRuns(block, true), blockMarks);
+      // the change tag participates in the rendered text but carries no offsets
+      const mappedRuns: StyleRun[] =
+        block.type !== "same" ? [...runs, { text: ` [${tagLabel(block)}]`, role: "plain", start: null }] : runs;
+      children.push(
+        <box key={dispIdx} id={`plan-block-${dispIdx}`} style={{ flexDirection: "row", marginTop: gap }}>
+          <text selectable={false}>
+            <span fg={isCursor ? tokens.accent : tokens.textDim}>{isCursor ? "▎ " : "  "}</span>
+            <span fg={tokens.textDim}>{marker(block)}</span>
+          </text>
+          <text
+            bg={isCursor ? tokens.cursorBg : undefined}
+            selectable
+            selectionBg={tokens.accent}
+            selectionFg={tokens.accentInk}
+            style={{ wrapMode: "word", flexGrow: 1, flexShrink: 1 }}
+            ref={(renderable: TextRenderable | null) => registerBlock(dispIdx, renderable, mappedRuns)}
+            onMouseUp={() => onLineActivate(dispIdx)}
+          >
+            {runs.map((run, runIndex) => (
+              <span key={runIndex} {...runStyle(run, block, tokens)}>
+                {run.text}
+              </span>
+            ))}
+            {block.type !== "same" ? <span fg={tagColor(block, tokens)}> [{tagLabel(block)}]</span> : null}
+          </text>
+        </box>,
+      );
+    }
+    if (compose && compose.dispIdx === dispIdx) {
+      children.push(
+        <AnnotationCard key={`compose-${dispIdx}`} kind={compose.kind} quote={compose.quote} draft={compose.draft} theme={theme} />,
+      );
+    }
+  }
+
+  return (
+    <box style={{ flexGrow: 1, flexDirection: "column" }}>
+      <SheetHeader session={session} onEditRequest={onEditRequest} theme={theme} />
+      {editOrphanCount > 0 ? (
+        <box style={{ height: 1, backgroundColor: tokens.markCommentBg, paddingLeft: 2 }}>
+          <text fg={tokens.red}>
+            {editOrphanCount} annotation{editOrphanCount === 1 ? "" : "s"} no longer match - the passage was removed.
+          </text>
+        </box>
+      ) : null}
+      <scrollbox ref={scrollRef} style={{ flexGrow: 1, paddingLeft: 2, paddingTop: 1 }} focused={false}>
+        {children}
+      </scrollbox>
+    </box>
+  );
+});
+
+/** Sheet chrome: submitted-by + revision delta left, the Edit word-button right. */
+function SheetHeader({
+  session,
+  onEditRequest,
+  theme,
+}: {
+  session: ReviewSession;
+  onEditRequest: () => void;
+  theme?: Theme;
+}): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const revisionCount = session.revisions.length;
+  const previous = revisionCount > 1 ? session.revisions[revisionCount - 2] : undefined;
+  const delta = previous ? revisionDelta(previous.content, session.artifact.content) : null;
+  return (
+    <box style={{ height: 1, flexDirection: "row", paddingLeft: 2, paddingRight: 1 }}>
+      <text fg={tokens.textDim}>
+        submitted by <span fg={tokens.textMuted}>{session.artifact.meta.agent ?? "unknown"}</span> · revision {revisionCount}
+        {delta ? (
+          <span fg={tokens.green}>
+            {" "}· v{revisionCount - 1}→v{revisionCount} +{delta.added} -{delta.removed}
+          </span>
+        ) : null}
+      </text>
+      <box style={{ flexGrow: 1 }} />
+      <Toolbar>
+        <Button onPress={onEditRequest} theme={theme}>
+          {" Edit "}
+        </Button>
+      </Toolbar>
+    </box>
+  );
+}
+
+/** Vertical rhythm: gaps live ABOVE blocks so boundaries never collapse. */
+function topGap(previous: DisplayBlock | undefined, current: DisplayBlock): number {
+  if (!previous) return 0;
+  const tightPair =
+    (current.kind === "li" && previous.kind === "li") || (current.kind === "oli" && previous.kind === "oli");
+  return tightPair ? 0 : 1;
+}
+
+function marker(block: DisplayBlock): string {
+  if (block.kind === "li") return "- ";
+  if (block.kind === "oli") return `${block.oliNum ?? 1}. `;
+  if (block.kind === "quote") return "▏ ";
+  return "";
+}
+
+function tagLabel(block: DisplayBlock): "cut" | "new" | "edited" {
+  return block.type === "del" ? "cut" : block.type === "add" ? "new" : "edited";
+}
+
+function tagColor(block: DisplayBlock, tokens: Theme): string {
+  return block.type === "del" ? tokens.red : block.type === "add" ? tokens.green : tokens.accent;
+}
+
+function runStyle(run: StyleRun, block: DisplayBlock, tokens: Theme): { fg?: string; bg?: string } {
+  const headingFg = block.kind === "h1" ? tokens.text : block.kind === "h2" || block.kind === "h3" ? tokens.accent : undefined;
+  const struck = block.type === "del";
+  switch (run.role) {
+    case "ins":
+      return { fg: tokens.insFg };
+    case "del":
+      return { fg: tokens.delFg };
+    case "mark-comment":
+      return { fg: tokens.text, bg: tokens.markCommentBg };
+    case "mark-suggestion":
+      return { fg: tokens.text, bg: tokens.markSuggestionBg };
+    case "mark-focus":
+      return { fg: tokens.accentInk, bg: tokens.accent };
+    case "kspan":
+      return { fg: tokens.accentInk, bg: tokens.accent };
+    default:
+      return { fg: struck ? tokens.red : (headingFg ?? tokens.text) };
+  }
+}

package/src/components/ReviewRail.stories.tsx

@@ -0,0 +1,103 @@
+import React from "react";
+import { DARK } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { ReviewRail } from "./ReviewRail";
+import { FIXTURE_ANNOTATIONS, fixturePlanSession } from "./story-fixtures";
+
+export const meta: StoryMeta = { title: "ReviewRail" };
+
+const callbacks = {
+  onTabChange: () => {},
+  onSelectCard: () => {},
+  onActivateCard: () => {},
+  onSubmitRequest: () => {},
+};
+
+/** The rail expects a height-constrained parent, like the app's main row. */
+function RailFrame({ children }: { children: React.ReactNode }): React.ReactNode {
+  return <box style={{ flexDirection: "row", width: "100%", height: "100%" }}>{children}</box>;
+}
+
+export const AnnotationStack: Story = {
+  render: () => (
+    <RailFrame>
+      <ReviewRail
+      session={fixturePlanSession()}
+      selectedId={FIXTURE_ANNOTATIONS[0]!.id}
+      resolvedIds={new Set(FIXTURE_ANNOTATIONS.map((annotation) => annotation.id))}
+      railTab="review"
+      pendingCount={2}
+      cardEdit={null}
+      submitConfirm={null}
+      {...callbacks}
+      />
+    </RailFrame>
+  ),
+  expectedColors: [DARK.panel, DARK.green],
+  size: { width: 40, height: 24 },
+};
+
+export const AgentTab: Story = {
+  render: () => (
+    <RailFrame>
+      <ReviewRail
+      session={fixturePlanSession()}
+      resolvedIds={new Set()}
+      railTab="agent"
+      pendingCount={2}
+      cardEdit={null}
+      submitConfirm={null}
+      {...callbacks}
+      />
+    </RailFrame>
+  ),
+  size: { width: 40, height: 24 },
+};
+
+export const SubmitConfirmOpen: Story = {
+  render: () => (
+    <RailFrame>
+      <ReviewRail
+      session={fixturePlanSession()}
+      resolvedIds={new Set()}
+      railTab="review"
+      pendingCount={2}
+      cardEdit={null}
+      submitConfirm={{
+        verdict: "request_changes",
+        summary: "",
+        annotationCount: 2,
+        blockingCount: 0,
+        onInput: () => {},
+        onSelectVerdict: () => {},
+        onSubmit: () => {},
+        onCancel: () => {},
+      }}
+      {...callbacks}
+      />
+    </RailFrame>
+  ),
+  expectedColors: [DARK.red],
+  size: { width: 40, height: 30 },
+};
+
+export const Resolved: Story = {
+  render: () => (
+    <RailFrame>
+      <ReviewRail
+      session={fixturePlanSession({
+        status: "resolved",
+        verdict: { kind: "approve", summary: "", feedback: "", resolvedAt: "2026-01-01T00:00:00Z" },
+      })}
+      resolvedIds={new Set()}
+      railTab="review"
+      pendingCount={0}
+      cardEdit={null}
+      submitConfirm={null}
+      {...callbacks}
+      />
+    </RailFrame>
+  ),
+  expectedColors: [DARK.green],
+  size: { width: 40, height: 24 },
+};

package/src/components/ReviewRail.tsx

@@ -0,0 +1,158 @@
+/**
+ * The right review rail: tab strip (Review/Agent), the scrollable annotation
+ * stack, and the pinned submit affordance. The confirm card sits OUTSIDE the
+ * scrollbox so the stack scrolls while the card stays at the rail bottom.
+ * Card reveal goes through the scrollbox's own scrollChildIntoView - no
+ * hardcoded card-height arithmetic.
+ */
+
+import React, { forwardRef, useImperativeHandle, useRef } from "react";
+import type { ScrollBoxRenderable } from "@opentui/core";
+import type { Annotation, ReviewSession } from "@cueloop/schema";
+import type { Theme } from "../theme";
+import { useComponentTheme } from "./theme-context";
+import { Tabs, Tab, TabList } from "./primitives/Tabs";
+import { Button } from "./primitives/Button";
+import { AnnotationCard, type AnnotationDraft } from "./AnnotationCard";
+import { ConfirmCard, type ConfirmCardProps } from "./ConfirmCard";
+
+export type RailTab = "review" | "agent";
+
+export interface RailCardEdit extends AnnotationDraft {
+  id: string;
+}
+
+export interface ReviewRailHandle {
+  /** Scroll the card for an annotation into view (selection symmetry). */
+  revealCard(annotationId: string): void;
+}
+
+export interface ReviewRailProps {
+  session: ReviewSession;
+  selectedId?: string;
+  /** Ids whose anchor resolved; null = orphan display off (diff view). */
+  resolvedIds: Set<string> | null;
+  railTab: RailTab;
+  pendingCount: number;
+  cardEdit: RailCardEdit | null;
+  submitConfirm: Omit<ConfirmCardProps, "theme"> | null;
+  onTabChange: (tab: RailTab) => void;
+  onSelectCard: (id: string) => void;
+  onActivateCard: (id: string) => void;
+  onSubmitRequest: () => void;
+  /** Rail column width; the app derives it from the terminal dimensions. */
+  width?: number;
+  theme?: Theme;
+}
+
+/** Forward-compatible: open annotation kinds may carry a blocking flag. */
+export function annotationBlocking(annotation: Annotation): boolean {
+  return (annotation as Annotation & { blocking?: boolean }).blocking === true;
+}
+
+export const ReviewRail = forwardRef<ReviewRailHandle, ReviewRailProps>(function ReviewRail(
+  {
+    session,
+    selectedId,
+    resolvedIds,
+    railTab,
+    pendingCount,
+    cardEdit,
+    submitConfirm,
+    onTabChange,
+    onSelectCard,
+    onActivateCard,
+    onSubmitRequest,
+    width = 34,
+    theme,
+  }: ReviewRailProps,
+  handleRef,
+): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const scrollRef = useRef<ScrollBoxRenderable | null>(null);
+
+  useImperativeHandle(handleRef, () => ({
+    revealCard: (annotationId: string): void => {
+      try {
+        scrollRef.current?.scrollChildIntoView(`annotation-card-${annotationId}`);
+      } catch {
+        // reveal is best-effort; selection state is already correct
+      }
+    },
+  }));
+
+  return (
+    <box style={{ width, backgroundColor: tokens.panel, flexDirection: "column", paddingLeft: 1, paddingTop: 1 }}>
+      <Tabs selectedKey={railTab} onSelectionChange={(key) => onTabChange(key as RailTab)} theme={theme}>
+        <TabList>
+          <Tab id="review">{`Review (${pendingCount})`}</Tab>
+          <Tab id="agent">Agent</Tab>
+        </TabList>
+      </Tabs>
+      <text> </text>
+      {railTab === "agent" ? (
+        <AgentTab session={session} theme={theme} />
+      ) : (
+        <>
+          {session.workingCopy !== undefined ? <text fg={tokens.textDim}>± plan edits → one diff</text> : null}
+          {session.annotations.length === 0 ? (
+            <text fg={tokens.textDim}>no annotations yet</text>
+          ) : (
+            <scrollbox ref={scrollRef} style={{ flexGrow: 1 }} focused={false}>
+              {session.annotations.map((annotation) => (
+                <AnnotationCard
+                  key={annotation.id}
+                  id={`annotation-card-${annotation.id}`}
+                  kind={annotation.kind}
+                  quote={annotation.anchor.quote}
+                  theme={theme}
+                  saved={{
+                    body: annotation.body,
+                    isSelected: annotation.id === selectedId,
+                    isOrphan: resolvedIds !== null && !resolvedIds.has(annotation.id),
+                    isBlocking: annotationBlocking(annotation),
+                    editing:
+                      cardEdit && cardEdit.id === annotation.id
+                        ? {
+                            text: cardEdit.text,
+                            onInput: cardEdit.onInput,
+                            onSave: cardEdit.onSave,
+                            onCancel: cardEdit.onCancel,
+                          }
+                        : null,
+                    onPress: () =>
+                      annotation.id === selectedId ? onActivateCard(annotation.id) : onSelectCard(annotation.id),
+                  }}
+                />
+              ))}
+            </scrollbox>
+          )}
+          <box style={{ flexGrow: 1 }} />
+          {/* the confirm card sits OUTSIDE the scrollbox: the annotation stack
+              above scrolls while the card stays pinned to the rail bottom */}
+          {session.status === "resolved" ? (
+            <text fg={tokens.green}>resolved: {session.verdict!.kind.replace("_", " ")}</text>
+          ) : submitConfirm ? (
+            <ConfirmCard {...submitConfirm} theme={theme} />
+          ) : (
+            <Button variant="accent-text" onPress={onSubmitRequest} theme={theme}>
+              {`Submit review (${pendingCount}) ⏎`}
+            </Button>
+          )}
+        </>
+      )}
+    </box>
+  );
+});
+
+/** Agent tab: who submitted, where the session stands, which revision. */
+function AgentTab({ session, theme }: { session: ReviewSession; theme?: Theme }): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  return (
+    <box style={{ flexDirection: "column", flexGrow: 1 }}>
+      <text fg={tokens.textMuted}>{session.artifact.meta.agent ?? "unknown"}</text>
+      <text fg={tokens.textDim}>status: {session.status}</text>
+      <text fg={tokens.textDim}>revision {session.revisions.length}</text>
+    </box>
+  );
+}

package/src/components/SettingsDialog.stories.tsx

@@ -0,0 +1,63 @@
+import React from "react";
+import { DARK } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { SettingsDialog, type SettingsCategory } from "./SettingsDialog";
+
+export const meta: StoryMeta = { title: "SettingsDialog" };
+
+const CATEGORIES: SettingsCategory[] = [
+  {
+    id: "general",
+    name: "General",
+    description: "identity and submission",
+    rows: [
+      { key: "displayName", label: "Display name", kind: "text" },
+      { key: "autoClose", label: "Auto-close on submit", kind: "cycle", options: ["off", "3s", "on"] },
+    ],
+  },
+  {
+    id: "display",
+    name: "Display",
+    description: "plan width and chrome",
+    rows: [
+      { key: "planWidth", label: "Plan width", kind: "cycle", options: ["default", "wide", "full"] },
+      { key: "showLineNumbers", label: "Line numbers", kind: "toggle" },
+    ],
+  },
+];
+
+const VALUES = { displayName: "amber-heron", autoClose: "3s", planWidth: "default", showLineNumbers: true };
+
+export const NavZone: Story = {
+  render: () => (
+    <SettingsDialog
+      isOpen
+      categories={CATEGORIES}
+      values={VALUES}
+      activeCategoryId="general"
+      activeRowIndex={0}
+      activeZone="nav"
+      onCategorySelect={() => {}}
+      onRowActivate={() => {}}
+    />
+  ),
+  expectedColors: [DARK.accent, DARK.backdrop],
+  size: { width: 100, height: 30 },
+};
+
+export const BodyZone: Story = {
+  render: () => (
+    <SettingsDialog
+      isOpen
+      categories={CATEGORIES}
+      values={VALUES}
+      activeCategoryId="display"
+      activeRowIndex={1}
+      activeZone="body"
+      onCategorySelect={() => {}}
+      onRowActivate={() => {}}
+    />
+  ),
+  expectedColors: [DARK.green],
+  size: { width: 100, height: 30 },
+};