@cueloop/client 0.1.0-alpha.9 → 0.1.0-alpha.91

package/src/test-support.ts

@@ -0,0 +1,369 @@
+/**
+ * Shared driving helpers for the virtual-terminal App suites: an input settles
+ * when its painted frame stops changing across consecutive event-loop turns
+ * (macrotask yield, render pass, visual-idle wait per turn) - no fixed-duration
+ * sleeps. Waits on daemon round-trips go through waitForFrame/waitFor with
+ * generous pass budgets.
+ */
+
+import { join } from "node:path";
+import { cloneElement, isValidElement, type ReactNode } from "react";
+import type { TestRendererOptions, TestRendererSetup } from "@opentui/core/testing";
+import { testRender } from "@opentui/react/test-utils";
+import type { AppProps } from "./App";
+
+/**
+ * A probe for the App's ready signal in an in-process suite: pass `onReady`
+ * to the App and await `ready` before the first interaction, instead of
+ * waiting for a piece of text and hoping the keyboard is bound by then.
+ */
+export interface AppReadyProbe {
+  /** Pass as the App's `onReady` prop. */
+  onReady: () => void;
+  /** Resolves once the App has fired its ready signal. */
+  ready: Promise<void>;
+}
+
+export function appReadyProbe(): AppReadyProbe {
+  let resolve: () => void = () => {};
+  const ready = new Promise<void>((done) => {
+    resolve = done;
+  });
+
+  return { onReady: () => resolve(), ready };
+}
+
+/**
+ * Boot an App element and resolve once it has fired its ready signal: the
+ * first usable screen is painted and its keyboard handlers are subscribed.
+ * Every App suite starts here so no boot waits on a piece of text and hopes.
+ */
+export async function renderReadyApp(
+  element: ReactNode,
+  options: TestRendererOptions,
+): Promise<TestRendererSetup> {
+  if (!isValidElement<AppProps>(element)) throw new Error("renderReadyApp needs an App element");
+  const probe = appReadyProbe();
+  const setup = await testRender(cloneElement(element, { onReady: probe.onReady }), options);
+
+  await probe.ready;
+
+  return setup;
+}
+
+/**
+ * The CUELOOP_CONFIG path that isolates a test from the developer's real user
+ * config: a file inside the test home that does not exist unless the test
+ * writes it. Subprocess harnesses set this in the child env; in-process suites
+ * use `isolateUserConfig`.
+ */
+export function isolatedUserConfigPath(home: string, fileName = "no-config.toml"): string {
+  return join(home, fileName);
+}
+
+/**
+ * Isolate the user config: point CUELOOP_CONFIG into the test home so
+ * loadConfig never reads the developer's real ~/.config/cueloop (a persisted
+ * review_state would change what char frames render locally while CI stays
+ * clean). The default file name does not exist, so loadConfig returns
+ * defaults; pass a file name for suites that write and assert a config of
+ * their own. Call in beforeEach; invoke the returned restore in afterEach.
+ */
+export function isolateUserConfig(home: string, fileName?: string): () => void {
+  const priorUserConfig = process.env.CUELOOP_CONFIG;
+
+  process.env.CUELOOP_CONFIG = isolatedUserConfigPath(home, fileName);
+
+  return () => {
+    if (priorUserConfig === undefined) delete process.env.CUELOOP_CONFIG;
+    else process.env.CUELOOP_CONFIG = priorUserConfig;
+  };
+}
+
+declare global {
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+
+/** The harness drives the real event loop by design; keep React's act warning off. */
+export function allowEventLoopUpdates(): void {
+  globalThis.IS_REACT_ACT_ENVIRONMENT = false;
+}
+
+/** Turns of the event loop a frame must survive unchanged before an input counts as settled. */
+const SETTLE_QUIET_TURNS = 2;
+
+/** Upper bound on settle turns, so a surface that keeps changing never stalls a test. */
+const SETTLE_MAX_TURNS = 40;
+
+/** The painted frame with its colors, so a caret cell (background only) counts as a change. */
+function paintedFrame(setup: TestRendererSetup): string {
+  return JSON.stringify(
+    setup
+      .captureSpans()
+      .lines.map((line) =>
+        line.spans.map((span) => [span.text, span.fg?.toInts(), span.bg?.toInts()]),
+      ),
+  );
+}
+
+/**
+ * Wait for an input to land: React commits its state on its own scheduler, which the renderer's
+ * idle check cannot see, so on a slow machine a single idle wait returns between the key and its
+ * paint. Instead, run turns of the loop until the painted frame is unchanged across
+ * `SETTLE_QUIET_TURNS` consecutive turns.
+ */
+export async function settle(setup: TestRendererSetup): Promise<void> {
+  allowEventLoopUpdates();
+  let previous = "";
+  let quietTurns = 0;
+
+  for (let turn = 0; turn < SETTLE_MAX_TURNS; turn++) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await setup.renderOnce();
+    await setup.waitForVisualIdle();
+    const frame = paintedFrame(setup);
+
+    quietTurns = frame === previous ? quietTurns + 1 : 0;
+    if (quietTurns >= SETTLE_QUIET_TURNS) return;
+    previous = frame;
+  }
+}
+
+/** Drive one key press: letters type as text; named keys use KeyCodes ids. */
+export async function press(setup: TestRendererSetup, key: string): Promise<void> {
+  if (key === "enter") setup.mockInput.pressKey("RETURN");
+  else if (key === "escape") setup.mockInput.pressKey("ESCAPE");
+  else if (key === "backspace") setup.mockInput.pressKey("BACKSPACE");
+  else if (key === "left") setup.mockInput.pressKey("ARROW_LEFT");
+  else if (key === "right") setup.mockInput.pressKey("ARROW_RIGHT");
+  else if (key === "up") setup.mockInput.pressKey("ARROW_UP");
+  else if (key === "down") setup.mockInput.pressKey("ARROW_DOWN");
+  else return typeText(setup, key);
+  await settle(setup);
+}
+
+export async function typeText(setup: TestRendererSetup, text: string): Promise<void> {
+  await setup.mockInput.typeText(text);
+  await settle(setup);
+}
+
+/** Drive one key press with modifiers: KeyCodes names ("ARROW_RIGHT") or single letters (ctrl+o). */
+export async function pressKey(
+  setup: TestRendererSetup,
+  key: string,
+  modifiers?: { shift?: boolean; ctrl?: boolean; meta?: boolean },
+): Promise<void> {
+  setup.mockInput.pressKey(key, modifiers);
+  await settle(setup);
+}
+
+/**
+ * Run a thread nav-mode command: esc drops the surface into nav mode, then a bare
+ * key acts (a letter, or a named key like "enter"/"backspace"). The caret and any
+ * held selection carry into nav, so the command lands where the caret is.
+ */
+export async function navCommand(setup: TestRendererSetup, key: string): Promise<void> {
+  await press(setup, "escape");
+  await new Promise((resolve) => setTimeout(resolve, 40));
+  await settle(setup);
+  // a single letter is a discrete keypress (nav command); named keys route through press
+  if (key.length === 1) await pressKey(setup, key);
+  else await press(setup, key);
+}
+
+/** A 0-based cell position within a captured char frame. */
+export interface FrameLocation {
+  row: number;
+  column: number;
+}
+
+/** Locate the first line of a text frame containing the needle; null when absent. */
+export function locateTextInFrame(frame: string, needle: string): FrameLocation | null {
+  for (const [row, line] of frame.split("\n").entries()) {
+    const column = line.indexOf(needle);
+
+    if (column !== -1) return { row, column };
+  }
+
+  return null;
+}
+
+/** Locate the first visual line containing the needle: 0-based row and start column. */
+export function locateText(setup: TestRendererSetup, needle: string): FrameLocation {
+  const frame = setup.captureCharFrame();
+  const location = locateTextInFrame(frame, needle);
+
+  if (location === null) {
+    throw new Error(`locateText ${JSON.stringify(needle)} not found.\nframe:\n${frame}`);
+  }
+
+  return location;
+}
+
+/** The 0-based visual row of the needle - for relative vertical-layout assertions. */
+export function frameRow(setup: TestRendererSetup, needle: string): number {
+  return locateText(setup, needle).row;
+}
+
+/** Click the first on-screen occurrence of the needle, offset in characters from its start. */
+export async function clickText(
+  setup: TestRendererSetup,
+  needle: string,
+  charOffset = 0,
+): Promise<void> {
+  const { row, column } = locateText(setup, needle);
+
+  await setup.mockMouse.click(column + charOffset, row);
+  await settle(setup);
+}
+
+/**
+ * Drag from the first occurrence of one needle to the first occurrence of
+ * another, `toCharOffset` characters past the second needle's start - so a
+ * character-precise selection can end inside or right after a word.
+ */
+export async function dragText(
+  setup: TestRendererSetup,
+  fromNeedle: string,
+  toNeedle: string,
+  toCharOffset = 0,
+): Promise<void> {
+  const from = locateText(setup, fromNeedle);
+  const to = locateText(setup, toNeedle);
+
+  await setup.mockMouse.drag(from.column, from.row, to.column + toCharOffset, to.row);
+  await settle(setup);
+}
+
+// Below the 60s per-test budget so a genuinely stuck wait throws its frame
+// error (useful) before bun's bare "timed out" fires. Generous because a
+// contended CI runner starves the render loop and daemon round-trips.
+const WAIT_DEADLINE_MS = 45_000;
+
+/** One macrotask turn: hands the event loop back so the in-process daemon can
+ *  read its socket and apply the write before the next poll. Tight render-pass
+ *  bursts starve that read on a contended CI runner - the round-trip then never
+ *  lands and the wait hangs the whole budget. */
+function yieldEventLoop(): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, 2));
+}
+
+/** Log a still-waiting line at most this often, so only genuinely slow (i.e.
+ *  flaking) waits are noisy; fast waits stay silent. */
+const PROGRESS_LOG_MS = 4000;
+
+/** The last render frame's tail, so a progress line shows what is on screen. */
+function frameTail(frame: string, rows = 6): string {
+  return frame.split("\n").slice(-rows).join("\n");
+}
+
+/**
+ * Poll gently: one render pass, one frame check, one macrotask yield. No
+ * multi-pass bursts, so the daemon (same event loop) always gets a turn to
+ * process IO between checks. The deadline bounds the whole wait. Slow waits log
+ * progress (poll count + frame-change count) so a CI stall shows whether the
+ * render froze or the content simply never arrived.
+ */
+async function waitForFramePredicate(
+  setup: TestRendererSetup,
+  predicate: (frame: string) => boolean,
+  label: string,
+): Promise<string> {
+  allowEventLoopUpdates();
+  const start = Date.now();
+  const deadline = start + WAIT_DEADLINE_MS;
+  let polls = 0;
+  let frameChanges = 0;
+  let lastFrame = "";
+  let lastLog = start;
+
+  for (;;) {
+    await setup.renderOnce();
+    const frame = setup.captureCharFrame();
+
+    polls++;
+    if (frame !== lastFrame) {
+      frameChanges++;
+      lastFrame = frame;
+    }
+    if (predicate(frame)) return frame;
+    const now = Date.now();
+
+    if (now > deadline) {
+      const frozen = frameChanges <= 1 ? " - render never advanced (frozen)" : "";
+
+      throw new Error(
+        `waitFor ${label} timed out after ${now - start}ms (${polls} polls, ${frameChanges} frame changes${frozen}).\nlast frame:\n${frame}`,
+      );
+    }
+    if (now - lastLog >= PROGRESS_LOG_MS) {
+      lastLog = now;
+      console.error(
+        `[waitFor] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes\n${frameTail(frame)}`,
+      );
+    }
+    await yieldEventLoop();
+  }
+}
+
+/** Wait until a state predicate holds (daemon round-trips included). */
+export async function waitForState(
+  setup: TestRendererSetup,
+  predicate: () => boolean,
+  label = "state",
+): Promise<void> {
+  allowEventLoopUpdates();
+  const start = Date.now();
+  const deadline = start + WAIT_DEADLINE_MS;
+  let polls = 0;
+  let frameChanges = 0;
+  let lastFrame = "";
+  let lastLog = start;
+
+  for (;;) {
+    if (predicate()) return;
+    await setup.renderOnce();
+    const frame = setup.captureCharFrame();
+
+    polls++;
+    if (frame !== lastFrame) {
+      frameChanges++;
+      lastFrame = frame;
+    }
+    if (predicate()) return;
+    const now = Date.now();
+
+    if (now > deadline) {
+      const frozen = frameChanges <= 1 ? " - render never advanced (frozen)" : "";
+
+      throw new Error(
+        `waitForState ${label} timed out after ${now - start}ms (${polls} polls, ${frameChanges} frame changes${frozen}).\nlast frame:\n${frame}`,
+      );
+    }
+    if (now - lastLog >= PROGRESS_LOG_MS) {
+      lastLog = now;
+      console.error(
+        `[waitForState] still waiting for ${label} - ${now - start}ms, ${polls} polls, ${frameChanges} frame changes`,
+      );
+    }
+    await yieldEventLoop();
+  }
+}
+
+/** Wait until the frame contains the needle (daemon round-trips included). */
+export async function waitForText(setup: TestRendererSetup, needle: string): Promise<string> {
+  return waitForFramePredicate(
+    setup,
+    (frame) => frame.includes(needle),
+    `text ${JSON.stringify(needle)}`,
+  );
+}
+
+/** Wait until the frame no longer contains the needle. */
+export async function waitForTextGone(setup: TestRendererSetup, needle: string): Promise<string> {
+  return waitForFramePredicate(
+    setup,
+    (frame) => !frame.includes(needle),
+    `text-gone ${JSON.stringify(needle)}`,
+  );
+}

package/src/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/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;
+}