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

package/src/components/syntax-highlight.ts

@@ -0,0 +1,133 @@
+/**
+ * Code highlighting tokens: the theme's named colors projected onto tree-sitter
+ * capture names. One group -> color map is the single source of truth, feeding
+ * both the native code renderable (via a cached SyntaxStyle per theme) and the
+ * diff sheet's per-row spans. Unknown languages simply render unstyled -
+ * highlighting is an enhancement, never a blocker.
+ */
+
+import {
+  SyntaxStyle,
+  infoStringToFiletype,
+  extensionToFiletype,
+  basenameToFiletype,
+} from "@opentui/core";
+import type { Theme } from "../theme";
+
+/** Markdown fence info -> tree-sitter filetype, with the aliases we accept. */
+export function filetypeFor(language?: string): string | undefined {
+  const info = (language ?? "").toLowerCase();
+
+  if (!info) return undefined;
+  const aliases: SyntaxAliases = {
+    ts: "typescript",
+    js: "javascript",
+    py: "python",
+    rb: "ruby",
+    rs: "rust",
+    sh: "bash",
+    shell: "bash",
+    zsh: "bash",
+    yml: "yaml",
+  };
+
+  return infoStringToFiletype(aliases[info] ?? info) ?? aliases[info] ?? info;
+}
+
+/** A diff/code file path -> tree-sitter filetype, by basename then extension. */
+export function filetypeForPath(path: string): string | undefined {
+  const basename = path.split("/").pop() ?? path;
+  const byBasename = basenameToFiletype.get(basename);
+
+  if (byBasename) return byBasename;
+  const dotIndex = basename.lastIndexOf(".");
+
+  if (dotIndex <= 0) return undefined;
+
+  return extensionToFiletype.get(basename.slice(dotIndex + 1).toLowerCase());
+}
+
+interface SyntaxAliases {
+  [alias: string]: string;
+}
+
+interface SyntaxGroupStyle {
+  fg: string;
+  italic?: boolean;
+}
+
+interface SyntaxGroupStyles {
+  [group: string]: SyntaxGroupStyle;
+}
+
+/** The one group -> style map, keyed by tree-sitter capture name. */
+function syntaxGroupStyles(theme: Theme): SyntaxGroupStyles {
+  return {
+    default: { fg: theme.textMuted },
+    comment: { fg: theme.textDim, italic: true },
+    string: { fg: theme.green },
+    number: { fg: theme.blue },
+    constant: { fg: theme.blue },
+    boolean: { fg: theme.blue },
+    keyword: { fg: theme.accent },
+    operator: { fg: theme.textDim },
+    punctuation: { fg: theme.textDim },
+    function: { fg: theme.text },
+    method: { fg: theme.text },
+    type: { fg: theme.blue },
+    constructor: { fg: theme.blue },
+    variable: { fg: theme.textMuted },
+    property: { fg: theme.textMuted },
+    parameter: { fg: theme.textMuted },
+    tag: { fg: theme.accent },
+    attribute: { fg: theme.blue },
+  };
+}
+
+const syntaxStyleCache = new WeakMap<Theme, SyntaxStyle>();
+
+export function syntaxStyleFor(theme: Theme): SyntaxStyle {
+  const cached = syntaxStyleCache.get(theme);
+
+  if (cached) return cached;
+  const style = SyntaxStyle.fromStyles(syntaxGroupStyles(theme));
+
+  syntaxStyleCache.set(theme, style);
+
+  return style;
+}
+
+/** A one-group syntax style plus the styleId that paints a "/skill" reference in the accent color. */
+export interface ReferenceStyle {
+  style: SyntaxStyle;
+  styleId: number;
+}
+
+const referenceStyleCache = new WeakMap<Theme, ReferenceStyle>();
+
+export function referenceStyleFor(theme: Theme): ReferenceStyle {
+  const cached = referenceStyleCache.get(theme);
+
+  if (cached) return cached;
+  const entry: ReferenceStyle = {
+    style: SyntaxStyle.fromStyles({ reference: { fg: theme.accent } }),
+    styleId: 0,
+  };
+
+  entry.styleId = entry.style.getStyleId("reference") ?? 0;
+  referenceStyleCache.set(theme, entry);
+
+  return entry;
+}
+
+/** The foreground for a tree-sitter capture group; undefined when unstyled. */
+export function colorForSyntaxGroup(group: string, theme: Theme): string | undefined {
+  const styles = syntaxGroupStyles(theme);
+  const direct = styles[group];
+
+  if (direct) return direct.fg;
+  // capture names are dotted (e.g. "keyword.control"); match the broadest prefix
+  const base = group.split(".")[0]!;
+
+  return styles[base]?.fg;
+}

package/src/components/terminal-pane.test.tsx

@@ -0,0 +1,40 @@
+/** The embedded terminal renderable runs a real PTY child through Ghostty's VT and paints its screen; a live `printf` child must show up in the OpenTUI frame. Skipped where no prebuilt libghostty-vt ships for the platform. */
+
+import { describe, expect, test } from "bun:test";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { waitForText } from "../test-support";
+import {
+  embeddedTerminalAvailable,
+  registerTerminalPane,
+  TerminalPaneRenderable,
+} from "./terminal-pane";
+
+registerTerminalPane();
+
+describe("TerminalPaneRenderable", () => {
+  test.skipIf(!embeddedTerminalAvailable())(
+    "paints a live child process's output into the box",
+    async () => {
+      // Arrange / Act - a child that prints a known line
+      const setup = await testRender(
+        React.createElement("terminalPane", {
+          command: "/bin/sh",
+          args: ["-c", "printf 'HELLO-EMBED\\n'; sleep 5"],
+          style: { width: 40, height: 6 },
+        }),
+        { width: 40, height: 6 },
+      );
+
+      // Assert - the child's output reaches the painted frame via Ghostty
+      await waitForText(setup, "HELLO-EMBED");
+      setup.renderer.destroy();
+    },
+  );
+
+  test("exposes availability + the renderable class", () => {
+    // Assert - the module loads and reports platform support honestly
+    expect([true, false]).toContain(embeddedTerminalAvailable());
+    expect(TerminalPaneRenderable).toBeDefined();
+  });
+});

package/src/components/terminal-pane.ts

@@ -0,0 +1,199 @@
+/**
+ * An OpenTUI renderable that runs a real child process (a shell, cc, pi, codex)
+ * on a PTY and paints its live screen into the box - the terminal-in-the-rail
+ * primitive. It wires the forkpty shim (child + tty, ../pty) to a Ghostty VT emulator
+ * (ghostty-terminal.ts) and blits the emulator's cell grid every frame via
+ * OptimizedBuffer.setCell. Register once with `registerTerminalPane`, then use
+ * `<terminalPane command="claude" ... />` in the OpenTUI React tree.
+ */
+
+import { Renderable, RGBA, createTextAttributes, type RenderContext } from "@opentui/core";
+import type { OptimizedBuffer } from "@opentui/core";
+import type { RenderableOptions } from "@opentui/core";
+import { extend } from "@opentui/react";
+import { spawn, ptyAvailable, type IPty } from "../pty";
+import {
+  loadGhosttyTerminals,
+  type GhosttyColor,
+  type GhosttyTerminal,
+  type GhosttyTerminalFactory,
+} from "../ghostty-terminal";
+
+/** One shared VT library load; null when this platform ships no prebuilt dylib. */
+let ghosttyFactory: GhosttyTerminalFactory | null | undefined;
+
+function factory(): GhosttyTerminalFactory | null {
+  if (ghosttyFactory === undefined) ghosttyFactory = loadGhosttyTerminals();
+
+  return ghosttyFactory;
+}
+
+/** Whether the embedded terminal can run here: both native shims ship for this
+ *  platform (the Ghostty VT renderer and the forkpty PTY). */
+export function embeddedTerminalAvailable(): boolean {
+  return factory() !== null && ptyAvailable();
+}
+
+/** Props for `<terminalPane>`: the child to run plus its cwd/env and a plan-context seed. */
+export interface TerminalPaneOptions extends RenderableOptions {
+  /** The program to run, e.g. "claude" / "pi" / "codex" / a shell. */
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  /** Text left unsubmitted in the child after it starts (plan-context seed). */
+  seedText?: string;
+  /** Fired when the child process exits. */
+  onExit?: (exitCode: number) => void;
+}
+
+function terminalEnvironment(env: NodeJS.ProcessEnv) {
+  return Object.fromEntries(
+    Object.entries(env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  );
+}
+
+const encoder = new TextEncoder();
+const DEFAULT_FG = RGBA.fromInts(208, 208, 208, 255);
+const TRANSPARENT = RGBA.fromValues(0, 0, 0, 0);
+/** Glyph color under the block cursor (dark ink on the light cursor block). */
+const CURSOR_INK = RGBA.fromInts(20, 20, 24, 255);
+
+/** Runs a PTY child and paints its Ghostty-rendered screen into this box. */
+export class TerminalPaneRenderable extends Renderable {
+  private pty: IPty | null = null;
+  private vt: GhosttyTerminal | null = null;
+  private cols = 0;
+  private rows = 0;
+  // The seed is held until the child's first output, so it lands in a ready
+  // prompt rather than racing the harness's startup (readline/TUI not up yet).
+  private pendingSeed: string | undefined;
+  private readonly opts: TerminalPaneOptions;
+
+  constructor(ctx: RenderContext, options: TerminalPaneOptions) {
+    super(ctx, options);
+    this.opts = options;
+    this.focusable = true;
+  }
+
+  /** Start the child + emulator once real layout dimensions are known. */
+  private start(cols: number, rows: number): void {
+    const terminals = factory();
+
+    if (!terminals) return;
+    const vt = terminals.create(cols, rows);
+
+    if (!vt) return; // no emulator, no visible screen - do not spawn a blind child
+    this.vt = vt;
+    this.cols = cols;
+    this.rows = rows;
+    this.pendingSeed = this.opts.seedText;
+    this.pty = spawn(this.opts.command ?? process.env.SHELL ?? "/bin/sh", this.opts.args ?? [], {
+      name: "xterm-256color",
+      cols,
+      rows,
+      cwd: this.opts.cwd ?? process.cwd(),
+      env: this.opts.env ?? terminalEnvironment(process.env),
+    });
+    this.pty.onData((data) => {
+      // the shim streams a UTF-8-decoded string (split multibyte is handled); a
+      // rare non-UTF-8 byte arrives as U+FFFD - acceptable for agent TUIs.
+      this.vt?.write(encoder.encode(data));
+      if (this.pendingSeed !== undefined) {
+        this.pty?.write(this.pendingSeed);
+        this.pendingSeed = undefined;
+      }
+      this.requestRender();
+    });
+    this.pty.onExit(({ exitCode }) => this.opts.onExit?.(exitCode));
+  }
+
+  /** Send raw bytes to the child (a key's escape sequence, or pasted text). */
+  write(data: string): void {
+    this.pty?.write(data);
+  }
+
+  protected onResize(width: number, height: number): void {
+    if (width <= 0 || height <= 0) return;
+    if (!this.pty) {
+      this.start(width, height);
+
+      return;
+    }
+    if (width === this.cols && height === this.rows) return;
+    this.cols = width;
+    this.rows = height;
+    this.vt?.resize(width, height);
+    this.pty.resize(width, height);
+  }
+
+  protected renderSelf(buffer: OptimizedBuffer): void {
+    if (!this.vt) return;
+    for (let y = 0; y < this.height; y++) {
+      for (let x = 0; x < this.width; x++) {
+        const cell = this.vt.readCell(x, y);
+
+        // Skip an empty normal-width cell; the buffer already starts blank.
+        if (cell && cell.width === 0 && cell.codepoint === 0) continue;
+        const char = cell && cell.codepoint ? String.fromCodePoint(cell.codepoint) : " ";
+        let fg = cell ? resolveColor(cell.fg, DEFAULT_FG) : DEFAULT_FG;
+        let bg = cell ? resolveColor(cell.bg, TRANSPARENT) : TRANSPARENT;
+
+        if (cell?.inverse) [fg, bg] = [bg, fg];
+        const attributes = cell
+          ? createTextAttributes({
+              bold: cell.bold,
+              italic: cell.italic,
+              underline: cell.underline,
+              dim: cell.faint,
+              strikethrough: cell.strikethrough,
+            })
+          : 0;
+
+        buffer.setCell(this.x + x, this.y + y, char, fg, bg, attributes);
+      }
+    }
+    // cursor is active-area coords; equal to viewport at the bottom (the live
+    // typing case). It can drift if the child scrolls the viewport back.
+    const cursor = this.vt.readCursor();
+
+    if (cursor.visible && cursor.x < this.width && cursor.y < this.height) {
+      const under = this.vt.readCell(cursor.x, cursor.y);
+      const char = under && under.codepoint ? String.fromCodePoint(under.codepoint) : " ";
+
+      // a block cursor: paint the cell with fg/bg swapped
+      buffer.setCell(this.x + cursor.x, this.y + cursor.y, char, CURSOR_INK, DEFAULT_FG, 0);
+    }
+  }
+
+  /** Kill the child and free the VT. Idempotent - the detach path calls this
+   *  directly because the React reconciler removes a child without destroying it. */
+  shutdown(): void {
+    this.pty?.kill();
+    this.vt?.free();
+    this.pty = null;
+    this.vt = null;
+  }
+
+  protected destroySelf(): void {
+    this.shutdown();
+    super.destroySelf();
+  }
+}
+
+/** Map a Ghostty cell color to an OpenTUI RGBA, using `fallback` for the terminal default. */
+function resolveColor(color: GhosttyColor, fallback: RGBA): RGBA {
+  if (color.kind === "rgb") return RGBA.fromInts(color.r, color.g, color.b, 255);
+  if (color.kind === "palette") return RGBA.fromIndex(color.index);
+
+  return fallback;
+}
+
+let registered = false;
+
+/** Register `<terminalPane>` with the OpenTUI React reconciler (idempotent). */
+export function registerTerminalPane(): void {
+  if (registered) return;
+  registered = true;
+  extend({ terminalPane: TerminalPaneRenderable });
+}

package/src/components/theme-context.stories.tsx

@@ -0,0 +1,46 @@
+import React from "react";
+import { DARK, type Theme } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { ThemeProvider } from "./theme-context";
+import { Card } from "./primitives/Card";
+
+export const meta: StoryMeta = { title: "Foundations/Theme" };
+
+/** A high-contrast variant to prove tokens flow through the provider. */
+const HIGH_CONTRAST: Theme = { ...DARK, accent: "#00ffff", elevated: "#000000", border: "#ffffff" };
+
+export const ContextDefault: Story = {
+  render: () => (
+    <Card title=" default dark theme " contentRows={1}>
+      <text>no provider needed</text>
+    </Card>
+  ),
+  expectedColors: [DARK.elevated],
+};
+
+export const ProviderSwap: Story = {
+  render: () => (
+    <ThemeProvider theme={HIGH_CONTRAST}>
+      <Card title=" provider theme " contentRows={1} borderColor={HIGH_CONTRAST.accent}>
+        <text>tokens come from the provider</text>
+      </Card>
+    </ThemeProvider>
+  ),
+  expectedColors: ["#00ffff", "#000000"],
+};
+
+export const PropOverride: Story = {
+  render: () => (
+    <ThemeProvider theme={DARK}>
+      <Card
+        title=" prop-overridden theme "
+        contentRows={1}
+        theme={HIGH_CONTRAST}
+        borderColor={HIGH_CONTRAST.accent}
+      >
+        <text>the theme prop beats the context</text>
+      </Card>
+    </ThemeProvider>
+  ),
+  expectedColors: ["#00ffff"],
+};

package/src/components/theme-context.tsx

@@ -0,0 +1,37 @@
+/**
+ * Provider theming for the component system. The context default is the
+ * built-in dark theme, so embedding a component (or rendering a story) needs
+ * no provider at all. One ThemeProvider swap switches the live theme; every
+ * component also accepts an optional `theme` prop that overrides the context
+ * for explicit control. Components consume named tokens only - a hardcoded
+ * color inside components/ is a review rejection.
+ */
+
+import React, { createContext, useContext } from "react";
+import { DARK, type Theme } from "../theme";
+
+const ThemeContext = createContext<Theme>(DARK);
+
+export function ThemeProvider({
+  theme,
+  children,
+}: {
+  theme: Theme;
+  children: React.ReactNode;
+}): React.ReactNode {
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): Theme {
+  return useContext(ThemeContext);
+}
+
+/**
+ * Token resolution for a component: the explicit `theme` prop wins over the
+ * provider context, which defaults to the built-in dark theme.
+ */
+export function useComponentTheme(override?: Theme): Theme {
+  const contextTheme = useContext(ThemeContext);
+
+  return override ?? contextTheme;
+}

package/src/components/thread-tree.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+import type { Thread, WorkspaceKey } from "@cueloop/schema";
+import { groupInbox, projectName } from "./thread-tree";
+
+function session(id: string, title: string, rootCommit?: string, remote?: string): Thread {
+  const workspace: WorkspaceKey = { repoRoot: `/home/dev/${id}-checkout`, branch: "main" };
+  if (rootCommit !== undefined) workspace.rootCommit = rootCommit;
+  if (remote !== undefined) workspace.remote = remote;
+
+  return {
+    schemaVersion: "1",
+    id,
+    workspace,
+    artifact: { type: "plan", content: `# ${title}\n`, meta: { title } },
+    revisions: [],
+    annotations: [],
+    message: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00.000Z",
+  };
+}
+
+describe("projectName", () => {
+  test("prefers the remote basename and strips the .git suffix", () => {
+    // Arrange
+    const workspace: WorkspaceKey = {
+      repoRoot: "/tmp/whatever",
+      branch: "main",
+      remote: "git@github.com:acme/widget.git",
+    };
+
+    // Act
+    const name = projectName(workspace);
+
+    // Assert
+    expect(name).toBe("widget");
+  });
+
+  test("falls back to the working-tree folder name when there is no remote", () => {
+    // Arrange
+    const workspace: WorkspaceKey = { repoRoot: "/home/dev/cueloop", branch: "main" };
+
+    // Act
+    const name = projectName(workspace);
+
+    // Assert
+    expect(name).toBe("cueloop");
+  });
+});
+
+describe("groupInbox", () => {
+  test("splits repo-bound threads into Projects and the rest into Threads", () => {
+    // Arrange
+    const sessions = [
+      session("a", "Read the repo", "root-1", "git@github.com:acme/widget.git"),
+      session("b", "A loose idea"),
+    ];
+
+    // Act
+    const { rows, ordered } = groupInbox(sessions);
+
+    // Assert
+    const labels = rows.map((row) => `${row.kind}:${"label" in row ? row.label : row.id}`);
+    expect(labels).toEqual([
+      "section:Projects",
+      "project:widget",
+      "thread:a",
+      "section:Threads",
+      "thread:b",
+    ]);
+    expect(ordered.map((s) => s.id)).toEqual(["a", "b"]);
+  });
+
+  test("collapses threads sharing a root commit into one project", () => {
+    // Arrange
+    const sessions = [
+      session("a", "First", "root-1", "git@github.com:acme/widget.git"),
+      session("b", "Second", "root-1", "git@github.com:acme/widget.git"),
+    ];
+
+    // Act
+    const { rows, ordered } = groupInbox(sessions);
+
+    // Assert
+    const projectRows = rows.filter((row) => row.kind === "project");
+    expect(projectRows).toHaveLength(1);
+    expect(ordered).toHaveLength(2);
+  });
+
+  test("selectionIndex on each thread matches its position in ordered", () => {
+    // Arrange
+    const sessions = [session("a", "One", "root-1"), session("b", "Two")];
+
+    // Act
+    const { rows, ordered } = groupInbox(sessions);
+
+    // Assert
+    for (const row of rows) {
+      if (row.kind === "thread") expect(ordered[row.selectionIndex]!.id).toBe(row.id);
+    }
+  });
+
+  test("omits the Projects section when nothing is repo-bound", () => {
+    // Arrange
+    const sessions = [session("a", "Loose one"), session("b", "Loose two")];
+
+    // Act
+    const { rows } = groupInbox(sessions);
+
+    // Assert
+    expect(rows.some((row) => row.kind === "section" && row.label === "Projects")).toBe(false);
+    expect(rows.some((row) => row.kind === "section" && row.label === "Threads")).toBe(true);
+  });
+
+  test("a pinned thread lifts into a Starred section at the top, out of its normal group", () => {
+    // Arrange - one repo-bound thread, one standalone; pin the repo-bound one
+    const sessions = [session("a", "Pinned one", "root-1"), session("b", "Loose two")];
+
+    // Act
+    const { rows, ordered } = groupInbox(sessions, new Set(["a"]));
+
+    // Assert - Starred is the first section and holds thread a; a is gone from Projects
+    const sections = rows
+      .filter((row) => row.kind === "section")
+      .map((row) => (row.kind === "section" ? row.label : ""));
+
+    expect(sections[0]).toBe("Starred");
+    expect(sections).not.toContain("Projects"); // its only member was pinned away
+    expect(ordered[0]!.id).toBe("a"); // the cursor walks pinned threads first
+    const pinnedThreadIds = rows.filter((row) => row.kind === "thread").map((row) => row.id);
+
+    expect(pinnedThreadIds).toEqual(["a", "b"]);
+  });
+});