@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.70

package/src/components/story.ts

@@ -0,0 +1,142 @@
+/**
+ * The story contract. Every component file in components/ ships a
+ * colocated *.stories.tsx that exports `meta` plus named Story objects.
+ * The catalog IS the regression suite: stories.test.tsx walks every story,
+ * snapshots its char frame, and asserts declared colors against the styled
+ * spans; the `bun run stories` TUI renders the same objects interactively.
+ */
+
+import type React from "react";
+import type { TreeNode } from "./primitives/tree-model";
+
+export interface StoryMeta {
+  /** Catalog path, e.g. "primitives/Card". */
+  title: string;
+}
+
+export interface Story {
+  render: () => React.ReactNode;
+  /**
+   * Colors (hex tokens) that must appear among the rendered frame's styled
+   * spans - the color regression net for color-bearing stories.
+   */
+  expectedColors?: string[];
+  /** Virtual terminal size; defaults to 80x24. */
+  size?: { width: number; height: number };
+}
+
+export interface LoadedStory {
+  moduleTitle: string;
+  storyName: string;
+  story: Story;
+}
+
+export function isStory(value: unknown): value is Story {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "render" in value &&
+    typeof value.render === "function"
+  );
+}
+
+function isStoryMeta(value: unknown): value is StoryMeta {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "title" in value &&
+    typeof value.title === "string"
+  );
+}
+
+/** Import every *.stories.tsx next to the components and flatten the exports. */
+export async function loadStories(): Promise<LoadedStory[]> {
+  const glob = new Bun.Glob("**/*.stories.tsx");
+  const files = [...glob.scanSync({ cwd: import.meta.dir })].sort();
+  const loaded: LoadedStory[] = [];
+
+  for (const file of files) {
+    const moduleExports = await import(`${import.meta.dir}/${file}`);
+    const meta = moduleExports["meta"];
+    const moduleTitle = isStoryMeta(meta) ? meta.title : file.replace(/\.stories\.tsx$/, "");
+
+    for (const [exportName, exported] of Object.entries(moduleExports)) {
+      if (exportName === "meta" || !isStory(exported)) continue;
+      loaded.push({ moduleTitle, storyName: exportName, story: exported });
+    }
+  }
+
+  return loaded;
+}
+
+/** A folder node keeps its children array live so the builder can append to it. */
+interface StoryTreeFolder extends TreeNode {
+  children: TreeNode[];
+}
+
+// A component folder holding one story of its own name reads as one row, not a folder wrapping a single leaf.
+function hoistSingleStoryFolders(nodes: TreeNode[]): TreeNode[] {
+  return nodes.map((node) => {
+    if (node.children === undefined) return node;
+    const children = hoistSingleStoryFolders(node.children);
+    const onlyChild = children.length === 1 ? children[0] : undefined;
+    if (
+      onlyChild !== undefined &&
+      onlyChild.children === undefined &&
+      onlyChild.label === node.label
+    ) {
+      return onlyChild;
+    }
+
+    return { ...node, children };
+  });
+}
+
+/**
+ * Nest the flat catalog into folder/component groups by splitting each
+ * moduleTitle on "/". Each story becomes a leaf keyed `${moduleTitle}/${storyName}`
+ * under its component node; a component holding a single story of its own name
+ * collapses so its row IS that story leaf.
+ */
+export function buildStoryTree(stories: LoadedStory[]): TreeNode[] {
+  const roots: TreeNode[] = [];
+  const foldersByPath = new Map<string, StoryTreeFolder>();
+
+  for (const { moduleTitle, storyName } of stories) {
+    let siblings = roots;
+    let path = "";
+
+    for (const segment of moduleTitle.split("/")) {
+      path = path === "" ? segment : `${path}/${segment}`;
+      let folder = foldersByPath.get(path);
+      if (folder === undefined) {
+        folder = { id: path, label: segment, children: [] };
+        foldersByPath.set(path, folder);
+        siblings.push(folder);
+      }
+      siblings = folder.children;
+    }
+
+    siblings.push({ id: `${moduleTitle}/${storyName}`, label: storyName });
+  }
+
+  return hoistSingleStoryFolders(roots);
+}
+
+/** Component files that must carry stories: every .tsx that is not a story/test/prototype. */
+export function componentFilesMissingStories(): string[] {
+  const componentGlob = new Bun.Glob("**/*.tsx");
+  const files = [...componentGlob.scanSync({ cwd: import.meta.dir })];
+  const missing: string[] = [];
+
+  for (const file of files) {
+    if (file.endsWith(".stories.tsx") || file.endsWith(".test.tsx")) continue;
+    if (file.endsWith(".prototype.tsx")) continue;
+    if (file === "stories-app.tsx") continue;
+    const storiesSibling = file.replace(/\.tsx$/, ".stories.tsx");
+
+    if (!files.includes(storiesSibling)) missing.push(file);
+  }
+
+  return missing;
+}

package/src/components/syntax-highlight.ts

@@ -0,0 +1,110 @@
+/**
+ * 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;
+}
+
+/** 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/truncate-text.ts

@@ -0,0 +1,7 @@
+/** Truncate text to one line of at most maxLength characters, ellipsis-terminated. */
+
+export function truncateToSingleLine(value: string, maxLength: number): string {
+  const oneLine = value.replace(/\n/g, " ");
+
+  return oneLine.length > maxLength ? oneLine.slice(0, maxLength - 1) + "…" : oneLine;
+}