@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.101

package/src/appearance/theme-presets.test.ts

@@ -0,0 +1,51 @@
+/** The branded transparent theme adapts to the terminal background - a light terminal gets dark text instead of light-on-light - while the opaque palette presets ignore appearance. */
+
+import { describe, expect, test } from "bun:test";
+import { DARK, LIGHT } from "./theme";
+import { composeTheme, themeForName } from "./theme-presets";
+
+describe("themeForName appearance", () => {
+  test("the branded cueloop theme picks the light variant on a light terminal", () => {
+    // Assert
+    expect(themeForName("cueloop", "dark")).toBe(DARK);
+    expect(themeForName("cueloop", "light")).toBe(LIGHT);
+  });
+
+  test("defaults to the dark variant when appearance is unspecified", () => {
+    // Assert
+    expect(themeForName("cueloop")).toBe(DARK);
+  });
+
+  test("an unknown name falls back to the branded theme, still appearance-aware", () => {
+    // Assert
+    expect(themeForName("nope", "light")).toBe(LIGHT);
+    expect(themeForName("nope", "dark")).toBe(DARK);
+  });
+
+  test("an explicit opaque preset ignores appearance (it paints its own background)", () => {
+    // Assert
+    expect(themeForName("nord", "light")).toBe(themeForName("nord", "dark"));
+  });
+});
+
+describe("the branded variants", () => {
+  test("both keep the transparent background but the light variant darkens its text", () => {
+    // Assert
+    expect(DARK.background).toBe("transparent");
+    expect(LIGHT.background).toBe("transparent");
+    expect(LIGHT.text).toBe("#1c1d24");
+    expect(LIGHT.text).not.toBe(DARK.text);
+    expect(LIGHT.elevated).not.toBe(DARK.elevated);
+  });
+});
+
+describe("composeTheme", () => {
+  test("resolves the appearance base, then layers per-token overrides on top", () => {
+    // Act
+    const themed = composeTheme("cueloop", { accent: "#123456" }, "light");
+
+    // Assert
+    expect(themed.text).toBe(LIGHT.text);
+    expect(themed.accent).toBe("#123456");
+  });
+});

package/src/appearance/theme-presets.ts

@@ -0,0 +1,219 @@
+/**
+ * Named theme presets selectable from Settings and `[ui] theme`. The branded
+ * "cueloop" default keeps the transparent terminal-through look; each of the
+ * well-known palettes paints its own opaque background so it reads exactly like
+ * the published theme. Every preset fills the full Theme token contract, so a
+ * `[theme]` per-token override still layers cleanly on top of the chosen base.
+ *
+ * Each palette maps its first-party spec onto cueloop's semantic slots. Where a
+ * palette has no dedicated green (Rosé Pine), additions use its positive accent
+ * by that palette's own convention.
+ */
+
+import { DARK, LIGHT, type Theme } from "./theme";
+
+/** Terminal background appearance, reported by the terminal (OSC) or assumed dark. */
+export type Appearance = "dark" | "light";
+
+/** The branded transparent theme's variant for the detected terminal background. */
+function brandedTheme(appearance: Appearance): Theme {
+  return appearance === "light" ? LIGHT : DARK;
+}
+
+/** Selectable theme name; the persisted `[ui] theme` value and cycle key. */
+export type ThemeName =
+  | "cueloop"
+  | "rose-pine-moon"
+  | "catppuccin-mocha"
+  | "tokyo-night"
+  | "gruvbox-dark"
+  | "nord";
+
+/** The branded default; the base every layered config starts from. */
+export const DEFAULT_THEME_NAME: ThemeName = "cueloop";
+
+/** Rosé Pine Moon - rosepinetheme.com. Foam stands in for additions (no green in the palette). */
+const ROSE_PINE_MOON: Theme = {
+  background: "#232136",
+  panel: "#232136",
+  elevated: "#2a273f",
+  border: "#44415a",
+  text: "#e0def4",
+  textMuted: "#908caa",
+  textDim: "#6e6a86",
+  accent: "#ea9a97",
+  accentInk: "#232136",
+  warning: "#f6c177",
+  green: "#9ccfd8",
+  red: "#eb6f92",
+  blue: "#3e8fb0",
+  cursorBackground: "#382a2f",
+  markCommentBackground: "#382a37",
+  insertedForeground: "#9ccfd8",
+  deletedForeground: "#eb6f92",
+  insertedBackground: "#243a3f",
+  insertedEmphasisBackground: "#31555c",
+  deletedBackground: "#3a2530",
+  deletedEmphasisBackground: "#563643",
+  backdrop: "transparent",
+};
+
+/** Catppuccin Mocha - catppuccin.com. Mauve is the signature accent. */
+const CATPPUCCIN_MOCHA: Theme = {
+  background: "#1e1e2e",
+  panel: "#1e1e2e",
+  elevated: "#313244",
+  border: "#45475a",
+  text: "#cdd6f4",
+  textMuted: "#a6adc8",
+  textDim: "#6c7086",
+  accent: "#cba6f7",
+  accentInk: "#1e1e2e",
+  warning: "#fab387",
+  green: "#a6e3a1",
+  red: "#f38ba8",
+  blue: "#89b4fa",
+  cursorBackground: "#2e2740",
+  markCommentBackground: "#33222b",
+  insertedForeground: "#a6e3a1",
+  deletedForeground: "#f38ba8",
+  insertedBackground: "#26372b",
+  insertedEmphasisBackground: "#375140",
+  deletedBackground: "#382530",
+  deletedEmphasisBackground: "#553844",
+  backdrop: "transparent",
+};
+
+/** Tokyo Night - the folke "night" variant. Magenta is the signature accent. */
+const TOKYO_NIGHT: Theme = {
+  background: "#1a1b26",
+  panel: "#1a1b26",
+  elevated: "#292e42",
+  border: "#3b4261",
+  text: "#c0caf5",
+  textMuted: "#a9b1d6",
+  textDim: "#565f89",
+  accent: "#bb9af7",
+  accentInk: "#1a1b26",
+  warning: "#e0af68",
+  green: "#9ece6a",
+  red: "#f7768e",
+  blue: "#7aa2f7",
+  cursorBackground: "#2b2740",
+  markCommentBackground: "#2f2230",
+  insertedForeground: "#9ece6a",
+  deletedForeground: "#f7768e",
+  insertedBackground: "#233028",
+  insertedEmphasisBackground: "#33493a",
+  deletedBackground: "#32232e",
+  deletedEmphasisBackground: "#4d3543",
+  backdrop: "transparent",
+};
+
+/** Gruvbox Dark - morhetz/gruvbox, medium contrast. Orange is the warm signature accent. */
+const GRUVBOX_DARK: Theme = {
+  background: "#282828",
+  panel: "#282828",
+  elevated: "#3c3836",
+  border: "#504945",
+  text: "#ebdbb2",
+  textMuted: "#d5c4a1",
+  textDim: "#928374",
+  accent: "#fe8019",
+  accentInk: "#282828",
+  warning: "#fe8019",
+  green: "#b8bb26",
+  red: "#fb4934",
+  blue: "#83a598",
+  cursorBackground: "#3a2f20",
+  markCommentBackground: "#3a2823",
+  insertedForeground: "#b8bb26",
+  deletedForeground: "#fb4934",
+  insertedBackground: "#333521",
+  insertedEmphasisBackground: "#4a4d2c",
+  deletedBackground: "#3c2a24",
+  deletedEmphasisBackground: "#5a3a30",
+  backdrop: "transparent",
+};
+
+/** Nord - nordtheme.com, the official 16-color spec. Frost cyan is the signature accent. */
+const NORD: Theme = {
+  background: "#2e3440",
+  panel: "#2e3440",
+  elevated: "#3b4252",
+  border: "#434c5e",
+  text: "#eceff4",
+  textMuted: "#d8dee9",
+  textDim: "#4c566a",
+  accent: "#88c0d0",
+  accentInk: "#2e3440",
+  warning: "#d08770",
+  green: "#a3be8c",
+  red: "#bf616a",
+  blue: "#81a1c1",
+  cursorBackground: "#2a3540",
+  markCommentBackground: "#3a2f33",
+  insertedForeground: "#a3be8c",
+  deletedForeground: "#bf616a",
+  insertedBackground: "#333d33",
+  insertedEmphasisBackground: "#454f42",
+  deletedBackground: "#3c2f33",
+  deletedEmphasisBackground: "#544045",
+  backdrop: "transparent",
+};
+
+/** All selectable themes by name; "cueloop" is the branded transparent default. */
+export const THEME_PRESETS: Record<ThemeName, Theme> = {
+  cueloop: DARK,
+  "rose-pine-moon": ROSE_PINE_MOON,
+  "catppuccin-mocha": CATPPUCCIN_MOCHA,
+  "tokyo-night": TOKYO_NIGHT,
+  "gruvbox-dark": GRUVBOX_DARK,
+  nord: NORD,
+};
+
+/** Cycle order for the Settings theme row; the registry's insertion order, branded default first. */
+export const THEME_NAMES: ThemeName[] = [
+  "cueloop",
+  "rose-pine-moon",
+  "catppuccin-mocha",
+  "tokyo-night",
+  "gruvbox-dark",
+  "nord",
+];
+
+/** Human labels for the Settings cycle row, keyed by the persisted name. */
+export const THEME_LABELS: Record<ThemeName, string> = {
+  cueloop: "cueloop",
+  "rose-pine-moon": "Rosé Pine Moon",
+  "catppuccin-mocha": "Catppuccin Mocha",
+  "tokyo-night": "Tokyo Night",
+  "gruvbox-dark": "Gruvbox Dark",
+  nord: "Nord",
+};
+
+/**
+ * Resolve a persisted theme name to its token set. The branded "cueloop" theme
+ * (and any unknown name that falls back to it) adapts to the terminal
+ * background; the explicit palette presets paint their own opaque background, so
+ * they read the same on a light or dark terminal and ignore `appearance`.
+ */
+export function themeForName(name: string, appearance: Appearance = "dark"): Theme {
+  if (name === "cueloop") return brandedTheme(appearance);
+
+  return isThemeName(name) ? THEME_PRESETS[name] : brandedTheme(appearance);
+}
+
+/** A preset with the user's `[theme]` per-token overrides layered on top - the live-switch equivalent of config load. */
+export function composeTheme(
+  name: string,
+  overrides: Partial<Theme>,
+  appearance: Appearance = "dark",
+): Theme {
+  return { ...themeForName(name, appearance), ...overrides };
+}
+
+/** True when the name is a known preset (guards a persisted `[ui] theme` value). */
+export function isThemeName(name: string): name is ThemeName {
+  return name in THEME_PRESETS;
+}

package/src/appearance/theme.ts

@@ -0,0 +1,112 @@
+/**
+ * Semantic theme tokens. Values carry over from the design-system
+ * prototypes (tokens.css). One built-in dark theme for now; the theme
+ * registry (palette-derived themes, terminal theme, user overrides) layers
+ * on top of these slots without touching consumers.
+ */
+
+export interface Theme {
+  background: string;
+  panel: string;
+  elevated: string;
+  border: string;
+  text: string;
+  textMuted: string;
+  textDim: string;
+  accent: string;
+  accentInk: string;
+  warning: string;
+  green: string;
+  red: string;
+  blue: string;
+  cursorBackground: string;
+  markCommentBackground: string;
+  insertedForeground: string;
+  deletedForeground: string;
+  insertedBackground: string;
+  insertedEmphasisBackground: string;
+  deletedBackground: string;
+  deletedEmphasisBackground: string;
+  backdrop: string;
+}
+
+/**
+ * The dimmed variant behind the walk wizard: every reading color drops to
+ * the dim token so the file list stays legible context, not competition.
+ * Layout tokens (backgrounds, cursor) keep their values.
+ */
+export function dimmedTheme(theme: Theme): Theme {
+  return {
+    ...theme,
+    text: theme.textDim,
+    textMuted: theme.textDim,
+    accent: theme.textDim,
+    warning: theme.textDim,
+    green: theme.textDim,
+    red: theme.textDim,
+    blue: theme.textDim,
+    insertedForeground: theme.textDim,
+    deletedForeground: theme.textDim,
+    insertedBackground: theme.panel,
+    insertedEmphasisBackground: theme.elevated,
+    deletedBackground: theme.panel,
+    deletedEmphasisBackground: theme.elevated,
+  };
+}
+
+export const DARK: Theme = {
+  /* Unpainted so the terminal background shows through; override in [theme]. */
+  background: "transparent",
+  panel: "transparent",
+  elevated: "#23232f",
+  border: "#3a3a4a",
+  text: "#e4e6ec",
+  textMuted: "#b1b6c4",
+  textDim: "#6b7280",
+  accent: "#cba6f7",
+  accentInk: "#17171a",
+  warning: "#e5a45c",
+  green: "#62d96b",
+  red: "#f08080",
+  blue: "#a9c8f5",
+  cursorBackground: "#33262a",
+  markCommentBackground: "#3d2a2e",
+  insertedForeground: "#62d96b",
+  deletedForeground: "#ff6b6b",
+  insertedBackground: "#16321d",
+  insertedEmphasisBackground: "#245c30",
+  deletedBackground: "#341c1f",
+  deletedEmphasisBackground: "#5a2a2e",
+  backdrop: "transparent",
+};
+
+/**
+ * The branded transparent theme for a LIGHT terminal: same unpainted
+ * background, but every reading color darkens so text is legible on a white
+ * terminal instead of light-on-light. Chosen when the terminal reports a light
+ * background; the dark variant above is the default and the fallback.
+ */
+export const LIGHT: Theme = {
+  background: "transparent",
+  panel: "transparent",
+  elevated: "#ececf2",
+  border: "#c7c7d2",
+  text: "#1c1d24",
+  textMuted: "#4b5162",
+  textDim: "#868c9c",
+  accent: "#5b3ea6",
+  accentInk: "#fbfbfa",
+  warning: "#a45f12",
+  green: "#2f8a3e",
+  red: "#c0392b",
+  blue: "#2f6fb0",
+  cursorBackground: "#e6e2ea",
+  markCommentBackground: "#f2e2e8",
+  insertedForeground: "#2f8a3e",
+  deletedForeground: "#c0392b",
+  insertedBackground: "#d8f5dd",
+  insertedEmphasisBackground: "#a9e6b6",
+  deletedBackground: "#fbdcdc",
+  deletedEmphasisBackground: "#f5b7b7",
+  backdrop: "transparent",
+};

package/src/appearance/visual/contrast.test.ts

@@ -0,0 +1,35 @@
+import { expect, test } from "bun:test";
+import { themeForName } from "../theme-presets";
+import { contrastRatio, relativeLuminance, rgbColorFromHex } from "./contrast";
+
+test("relativeLuminance ranks black below white", () => {
+  expect(relativeLuminance([0, 0, 0])).toBe(0);
+  expect(relativeLuminance([255, 255, 255])).toBeCloseTo(1, 5);
+});
+
+test("contrastRatio is symmetric and peaks at black on white", () => {
+  expect(contrastRatio([0, 0, 0], [255, 255, 255])).toBeCloseTo(21, 0);
+  expect(contrastRatio([255, 255, 255], [0, 0, 0])).toBeCloseTo(21, 0);
+  expect(contrastRatio([100, 100, 100], [100, 100, 100])).toBeCloseTo(1, 5);
+});
+
+// The branded theme is terminal-through, so text sits on a real terminal background, not pure black or
+// white; gate each theme against a representative one so a low-contrast token cannot hide behind an extreme.
+const TERMINAL_BACKGROUND = {
+  dark: rgbColorFromHex("#1e1e2e"),
+  light: rgbColorFromHex("#f0f0f0"),
+} as const;
+const MIN_NORMAL_TEXT_CONTRAST = 4.5;
+
+for (const mode of ["dark", "light"] as const) {
+  test(`${mode} theme keeps text, muted text, and accent legible on its terminal`, () => {
+    const theme = themeForName("cueloop", mode);
+    const background = TERMINAL_BACKGROUND[mode];
+
+    for (const token of [theme.text, theme.textMuted, theme.accent]) {
+      expect(contrastRatio(rgbColorFromHex(token), background)).toBeGreaterThanOrEqual(
+        MIN_NORMAL_TEXT_CONTRAST,
+      );
+    }
+  });
+}

package/src/appearance/visual/contrast.ts

@@ -0,0 +1,33 @@
+/** WCAG relative luminance and contrast ratio for the visual-regression accessibility gate. */
+
+export type RgbColor = readonly [number, number, number];
+
+/** Parse a `#rrggbb` hexadecimal colour into an sRGB triple (channels 0-255). */
+export function rgbColorFromHex(hex: string): RgbColor {
+  const value = hex.replace("#", "");
+
+  return [
+    Number.parseInt(value.slice(0, 2), 16),
+    Number.parseInt(value.slice(2, 4), 16),
+    Number.parseInt(value.slice(4, 6), 16),
+  ];
+}
+
+/** WCAG relative luminance of an sRGB colour, 0 (black) to 1 (white). */
+export function relativeLuminance(rgb: RgbColor): number {
+  const linear = rgb.map((channel) => {
+    const ratio = channel / 255;
+
+    return ratio <= 0.03928 ? ratio / 12.92 : ((ratio + 0.055) / 1.055) ** 2.4;
+  });
+
+  return 0.2126 * linear[0]! + 0.7152 * linear[1]! + 0.0722 * linear[2]!;
+}
+
+/** WCAG contrast ratio between two sRGB colours, 1 (identical) to 21 (black on white). */
+export function contrastRatio(foreground: RgbColor, background: RgbColor): number {
+  const lighter = Math.max(relativeLuminance(foreground), relativeLuminance(background));
+  const darker = Math.min(relativeLuminance(foreground), relativeLuminance(background));
+
+  return (lighter + 0.05) / (darker + 0.05);
+}

package/src/diff/components/AnnotatableFileView.stories.tsx

@@ -0,0 +1,42 @@
+import React from "react";
+import { SCHEMA_VERSION, type Thread } from "@cueloop/schema";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { AnnotatableFileView } from "./AnnotatableFileView";
+
+export const meta: StoryMeta = { title: "Surfaces/AnnotatableFileView" };
+
+const SAMPLE = `export function add(a: number, b: number): number {\n  return a + b;\n}\n`;
+
+const SESSION: Thread = {
+  schemaVersion: SCHEMA_VERSION,
+  id: "ses_story",
+  workspace: { repoRoot: "/repo", branch: "main" },
+  artifact: { type: "plan", content: "# Plan\n", meta: {} },
+  revisions: [{ revision: 1, content: "# Plan\n", submittedAt: "2026-01-01T00:00:00Z" }],
+  annotations: [],
+  message: null,
+  status: "pending",
+  createdAt: "2026-01-01T00:00:00Z",
+};
+
+const noop = (): void => {};
+
+export const Loaded: Story = {
+  render: () => (
+    <AnnotatableFileView
+      path="src/add.ts"
+      loadContents={() => Promise.resolve(SAMPLE)}
+      session={SESSION}
+      quickActions={[]}
+      observer={false}
+      onAddComment={noop}
+      onReply={noop}
+      onUpdateAnnotation={noop}
+      onExit={noop}
+      theme={DARK}
+    />
+  ),
+  expectedColors: [DARK.textDim],
+  size: { width: 60, height: 12 },
+};

package/src/diff/components/AnnotatableFileView.test.tsx

@@ -0,0 +1,157 @@
+/**
+ * A project file is its own annotation surface: selecting a line and typing leaves a comment whose
+ * anchor quotes that file line, handed up as an Anchor the app persists with a file target.
+ */
+
+import { describe, expect, mock, test } from "bun:test";
+import type { RGBA } from "@opentui/core";
+import { testRender } from "@opentui/react/test-utils";
+import React from "react";
+import { SCHEMA_VERSION, type Anchor, type Thread } from "@cueloop/schema";
+import { AnnotatableFileView } from "./AnnotatableFileView";
+import { DARK } from "../../appearance/theme";
+import {
+  allowEventLoopUpdates,
+  dragText,
+  typeText,
+  pressKey,
+  waitForText,
+} from "../../testing/test-support";
+
+const SAMPLE = "export function add(a: number, b: number) {\n  return a + b;\n}\n";
+
+function planSession(): Thread {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    id: "ses_plan",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: "# Plan\n", meta: {} },
+    revisions: [{ revision: 1, content: "# Plan\n", submittedAt: "2026-01-01T00:00:00Z" }],
+    annotations: [],
+    message: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00Z",
+  };
+}
+
+const noop = (): void => {};
+
+function colorHex(color: RGBA): string {
+  const [red, green, blue] = color.toInts();
+
+  return "#" + [red, green, blue].map((part) => part.toString(16).padStart(2, "0")).join("");
+}
+
+describe("AnnotatableFileView", () => {
+  for (const { path, source, keyword } of [
+    { path: "src/add.ts", source: "export const add = 1;", keyword: "export" },
+    { path: "src/add.js", source: "const add = 1;", keyword: "const" },
+  ]) {
+    test(`highlights ${path} by its detected language`, async () => {
+      allowEventLoopUpdates();
+      const setup = await testRender(
+        <AnnotatableFileView
+          path={path}
+          loadContents={() => Promise.resolve(source)}
+          session={planSession()}
+          quickActions={[]}
+          observer={false}
+          onAddComment={noop}
+          onReply={noop}
+          onUpdateAnnotation={noop}
+          onExit={noop}
+          theme={DARK}
+        />,
+        { width: 64, height: 12 },
+      );
+      let highlighted = false;
+
+      for (let attempt = 0; attempt < 60 && !highlighted; attempt++) {
+        await setup.renderOnce();
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        highlighted = setup.captureSpans().lines.some((line) =>
+          line.spans
+            .filter((span) => colorHex(span.fg) === DARK.accent)
+            .map((span) => span.text)
+            .join("")
+            .includes(keyword),
+        );
+      }
+
+      expect(highlighted).toBe(true);
+      setup.renderer.destroy();
+    }, 25000);
+  }
+
+  test("commenting a file line hands up an anchor that quotes the line", async () => {
+    const onAddComment = mock((_anchor: Anchor, _body: string) => {});
+    const setup = await testRender(
+      <AnnotatableFileView
+        path="src/add.ts"
+        loadContents={() => Promise.resolve(SAMPLE)}
+        session={planSession()}
+        quickActions={[]}
+        observer={false}
+        onAddComment={onAddComment}
+        onReply={noop}
+        onUpdateAnnotation={noop}
+        onExit={noop}
+        theme={DARK}
+      />,
+      { width: 64, height: 12 },
+    );
+
+    // Act - select the middle line, type a comment, send it
+    await waitForText(setup, "return a + b");
+    await dragText(setup, "return a + b", "return a + b", "return a + b".length);
+    await typeText(setup, "why not reduce?");
+    await pressKey(setup, "RETURN", { meta: true });
+
+    // Assert - the surface built an anchor quoting the file line and handed it up with the body
+    expect(onAddComment).toHaveBeenCalled();
+    const [anchor, body] = onAddComment.mock.calls[0]!;
+
+    expect(anchor.quote).toContain("return a + b");
+    expect(body).toContain("why not reduce?");
+
+    setup.renderer.destroy();
+  });
+
+  test("a head-side (deleted-line) note never rebinds onto the current file", async () => {
+    const session = planSession();
+
+    // a note left on the removed side of this file: the worktree view must not show it
+    session.annotations = [
+      {
+        id: "h1",
+        kind: "comment",
+        anchor: { quote: "return a + b", prefix: "", suffix: "" },
+        target: { kind: "file", path: "src/add.ts", rev: "head" },
+        body: "deleted-side note",
+        createdAt: "2026-01-01T00:00:00Z",
+      },
+    ];
+    const setup = await testRender(
+      <AnnotatableFileView
+        path="src/add.ts"
+        loadContents={() => Promise.resolve(SAMPLE)}
+        session={session}
+        quickActions={[]}
+        observer={false}
+        onAddComment={noop}
+        onReply={noop}
+        onUpdateAnnotation={noop}
+        onExit={noop}
+        theme={DARK}
+      />,
+      { width: 64, height: 12 },
+    );
+
+    await waitForText(setup, "return a + b");
+
+    // Assert - the current file shows, but the head-side note is not attached to it
+    expect(setup.captureCharFrame()).not.toContain("deleted-side note");
+
+    setup.renderer.destroy();
+  });
+});