@cueloop/client 0.1.0-alpha.53 → 0.1.0-alpha.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.53",
+  "version": "0.1.0-alpha.54",
   "description": "The cueloop review UI: projection renderer, keyboard grammar, review rail",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -26,10 +26,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/daemon": "0.1.0-alpha.53",
-    "@cueloop/extension-api": "0.1.0-alpha.53",
-    "@cueloop/integration-obsidian": "0.1.0-alpha.53",
-    "@cueloop/schema": "0.1.0-alpha.53",
+    "@cueloop/daemon": "0.1.0-alpha.54",
+    "@cueloop/extension-api": "0.1.0-alpha.54",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.54",
+    "@cueloop/schema": "0.1.0-alpha.54",
     "@opentui/core": "^0.5.8",
     "@opentui/keymap": "0.5.8",
     "@opentui/react": "^0.5.8",

package/src/App.appearance.test.tsx

@@ -0,0 +1,51 @@
+/** The App renders in a light virtual terminal: passing appearance="light" threads the light branded theme through the provider without breaking the mount (the char frame is color-blind, so this covers propagation and wiring, not the pixel colors). */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { DaemonServer } from "@cueloop/daemon";
+import type { ReviewSession } from "@cueloop/schema";
+import { App } from "./App";
+import { isolateUserConfig, settle, waitForText } from "./test-support";
+
+const PLAN = "# Sync Plan\n\n## Steps\n\n- flush the queue\n";
+
+let home: string;
+let server: DaemonServer;
+let session: ReviewSession;
+let restoreUserConfig: () => void;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-appearance-"));
+  restoreUserConfig = isolateUserConfig(home);
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  session = server.core.sessionCreate({
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: PLAN, meta: { title: "Sync Plan", planPath: "plan.md" } },
+  });
+});
+afterEach(() => {
+  restoreUserConfig();
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+describe("appearance", () => {
+  test("renders the review on a light terminal", async () => {
+    // Arrange + Act
+    const setup = await testRender(<App home={home} sessionId={session.id} appearance="light" />, {
+      width: 120,
+      height: 32,
+    });
+
+    // Assert
+    await waitForText(setup, "cueloop");
+    await waitForText(setup, "Sync Plan");
+    await settle(setup);
+    expect(setup.captureCharFrame()).toContain("flush the queue");
+  });
+});

package/src/App.tsx

@@ -22,7 +22,7 @@ import type { Clock, MouseEvent } from "@opentui/core";
 import { type VerdictKind } from "@cueloop/schema";
 import { displayText, marksByDisplay, spanFromRange, type Mark } from "./view-plan";
 import { noteForFile, viewedCount } from "./walk";
-import { DARK, dimmedTheme } from "./theme";
+import { dimmedTheme } from "./theme";
 import {
   DEFAULT_KEYS,
   DEFAULT_QUICK_ACTIONS,
@@ -39,6 +39,8 @@ import {
   DEFAULT_THEME_NAME,
   THEME_LABELS,
   THEME_NAMES,
+  themeForName,
+  type Appearance,
   type ThemeName,
 } from "./theme-presets";
 import type { Theme } from "./theme";
@@ -112,6 +114,12 @@ export interface AppProps {
    * name prompt so their notes attribute to a name, not a fingerprint.
    */
   selfAuthor?: string;
+  /**
+   * The terminal's background appearance (from an OSC query at startup). The
+   * branded transparent theme darkens its text on a light terminal so it is not
+   * light-on-light. Defaults to dark - the historical assumption.
+   */
+  appearance?: Appearance;
 }
 
 export function App({
@@ -123,6 +131,7 @@ export function App({
   openClient,
   role = "owner",
   selfAuthor,
+  appearance = "dark",
 }: AppProps): React.ReactNode {
   // Observer stays fully read-only; a collaborator writes annotations but not
   // the plan or a verdict. `observer` is what the controller and every write
@@ -200,7 +209,7 @@ export function App({
   // keymap from layered config; the loaded theme swaps the provider value
   const keysRef = useRef(DEFAULT_KEYS);
   const keyBindings = useMemo(() => new KeyBindings(DEFAULT_KEYS), []);
-  const [theme, setTheme] = useState(DARK);
+  const [theme, setTheme] = useState(() => themeForName(DEFAULT_THEME_NAME, appearance));
   const [themeName, setThemeName] = useState<ThemeName>(DEFAULT_THEME_NAME);
   const [themeOverrides, setThemeOverrides] = useState<Partial<Theme>>({});
   const [authorNames, setAuthorNames] = useState<Record<string, string>>({});
@@ -211,7 +220,7 @@ export function App({
     const config = loadConfig({ repoRoot: session?.workspace.repoRoot });
     keysRef.current = config.keys;
     keyBindings.setKeys(config.keys);
-    setTheme(config.theme);
+    setTheme(composeTheme(config.ui.theme, config.themeOverrides, appearance));
     setThemeName(config.ui.theme);
     setThemeOverrides(config.themeOverrides);
     setReviewMode(config.ui.reviewState);
@@ -221,7 +230,7 @@ export function App({
     setQuickActions(config.actions);
     setAutoClose(config.ui.autoClose);
     controller.applyConfig(config);
-  }, [session?.workspace.repoRoot, controller, keyBindings]);
+  }, [session?.workspace.repoRoot, controller, keyBindings, appearance]);
   useEffect(
     () => () => {
       if (pulseTimer.current) clearTimeout(pulseTimer.current);
@@ -541,7 +550,7 @@ export function App({
     } else if (rowKey === "theme") {
       const next = THEME_NAMES[(THEME_NAMES.indexOf(themeName) + 1) % THEME_NAMES.length]!;
       setThemeName(next);
-      setTheme(composeTheme(next, themeOverrides));
+      setTheme(composeTheme(next, themeOverrides, appearance));
       persistTheme(next);
     }
   };

package/src/run.ts

@@ -10,15 +10,21 @@ export interface RunClientOptions {
   home?: string;
 }
 
+/** OSC background query budget: brief so a terminal that never answers falls back to dark. */
+const THEME_QUERY_TIMEOUT_MS = 200;
+
 export async function runClient(options: RunClientOptions): Promise<number> {
   // mouse movement reporting makes multiplexers forward drags to the app,
   // so the renderer's native selection is the drag driver
   const renderer = await createCliRenderer({ enableMouseMovement: true });
+  const appearance =
+    (await renderer.waitForThemeMode(THEME_QUERY_TIMEOUT_MS).catch(() => null)) ?? "dark";
   return new Promise<number>((resolve) => {
     createRoot(renderer).render(
       React.createElement(App, {
         home: options.home,
         sessionId: options.sessionId,
+        appearance,
         onExit: (code: number) => {
           renderer.destroy();
           resolve(code);

package/src/serve.ts

@@ -22,6 +22,9 @@ import { createServer } from "@opentui/ssh";
 import { cueloopHome } from "@cueloop/daemon";
 import { App } from "./App";
 
+/** OSC background query budget: brief so a terminal that never answers falls back to dark. */
+const THEME_QUERY_TIMEOUT_MS = 200;
+
 export interface ServeOptions {
   /** TCP port for the SSH listener; 0 picks an ephemeral port. Default 2222. */
   port?: number;
@@ -56,13 +59,18 @@ export async function serveClient(options: ServeOptions = {}): Promise<ServeHand
     startupBanner: options.banner ?? true,
     idleTimeout: "2h",
     onError: options.onError,
-  }).serve((session) => {
+  }).serve(async (session) => {
+    // the observer's terminal reports its own background, so a light-terminal
+    // watcher gets the readable variant too
+    const appearance =
+      (await session.renderer.waitForThemeMode(THEME_QUERY_TIMEOUT_MS).catch(() => null)) ?? "dark";
     const root = createRoot(session.renderer);
     root.render(
       React.createElement(App, {
         home,
         sessionId: options.sessionId,
         readOnly: true,
+        appearance,
         // q disconnects only this observer, never the server
         onExit: () => session.end(),
       }),

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

@@ -10,7 +10,15 @@
  * by that palette's own convention.
  */
 
-import { DARK, type Theme } from "./theme";
+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 =
@@ -152,14 +160,24 @@ export const THEME_LABELS: Record<ThemeName, string> = {
   nord: "Nord",
 };
 
-/** Resolve a persisted theme name to its token set; unknown names fall back to the branded default. */
-export function themeForName(name: string): Theme {
-  return THEME_PRESETS[name as ThemeName] ?? DARK;
+/**
+ * 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 THEME_PRESETS[name as ThemeName] ?? 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>): Theme {
-  return { ...themeForName(name), ...overrides };
+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). */

package/src/theme.ts

@@ -65,3 +65,29 @@ export const DARK: Theme = {
   deletedForeground: "#ff6b6b",
   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: "#b5495b",
+  accentInk: "#ffffff",
+  green: "#2f8a3e",
+  red: "#c0392b",
+  blue: "#2f6fb0",
+  cursorBackground: "#e6e2ea",
+  markCommentBackground: "#f2e2e8",
+  insertedForeground: "#2f8a3e",
+  deletedForeground: "#c0392b",
+  backdrop: "transparent",
+};