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

package/src/kitty-image.ts

@@ -0,0 +1,138 @@
+/**
+ * Direct kitty graphics protocol emission for a cell rectangle. OpenTUI's
+ * ImageRenderable does not display in every terminal, so prototype review paints
+ * the screenshot itself: transmit the PNG once under a fixed image AND placement
+ * id, then re-place that same placement after each frame over its reserved
+ * (never-repainted) cells. Reusing one placement id means each frame REPLACES
+ * the placement rather than stacking a new one, which is the protocol's
+ * flicker-free move/resize path. Locally the PNG travels out of band via a
+ * temporary file so its bytes never cross the pty; a base64 fallback covers the
+ * ssh sharing path where no shared filesystem exists.
+ */
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface CellRegion {
+  /** 0-based screen cell of the region's top-left corner. */
+  column: number;
+  row: number;
+  columns: number;
+  rows: number;
+}
+
+/** Writes a raw sequence ordered against the renderer's own frame output. */
+export type OrderedWrite = (chunk: string) => void;
+
+export type TransmitMedium = "file" | "base64";
+
+const ESCAPE_STRING_TERMINATOR = "\x1b\\";
+const CHUNK_BYTES = 4096;
+// The protocol reserves values below INT32_MIN/2 for images that must sit
+// beneath cells with painted backgrounds, such as the marker popover.
+const IMAGE_Z_INDEX = -1_073_741_825;
+// One fixed placement per image: reusing it makes every put replace that
+// placement instead of accumulating a new one each frame.
+const PLACEMENT_ID = 1;
+const SYNCHRONIZED_UPDATE_START = "\x1b[?2026h";
+const SYNCHRONIZED_UPDATE_END = "\x1b[?2026l";
+
+let tempFileCounter = 0;
+let privateTempDir: string | null = null;
+
+/**
+ * base64 is the safe default: it works over the pty everywhere, including the
+ * ssh sharing path. Out-of-band file transfer (t=t) is faster for the initial
+ * transmit but depends on the terminal trusting the temp-file path, so it is
+ * opt-in via `CUELOOP_KITTY_FILE=1` and never used over ssh (no shared disk).
+ */
+export function resolveTransmitMedium(env: NodeJS.ProcessEnv = process.env): TransmitMedium {
+  if (env.CUELOOP_KITTY_FILE === "1" && !env.SSH_CONNECTION && !env.SSH_TTY) return "file";
+
+  return "base64";
+}
+
+/** Save the cursor, run the placement at the region's corner, restore it. */
+function atRegion(region: CellRegion, body: string): string {
+  const moveToCorner = `\x1b[${region.row + 1};${region.column + 1}H`;
+
+  return `\x1b7${moveToCorner}${body}\x1b8`;
+}
+
+function graphicsCommand(keys: string, payload: string): string {
+  return `\x1b_G${keys};${payload}${ESCAPE_STRING_TERMINATOR}`;
+}
+
+function placementKeys(imageId: number, region: CellRegion): string {
+  return `i=${imageId},p=${PLACEMENT_ID},q=2,C=1,z=${IMAGE_Z_INDEX},c=${region.columns},r=${region.rows}`;
+}
+
+// A per-process 0700 directory with an unpredictable name, so a local attacker
+// cannot pre-place a symlink at the screenshot path and redirect the write.
+function writeTempPng(png: Uint8Array): string {
+  if (!privateTempDir) privateTempDir = mkdtempSync(join(tmpdir(), "cueloop-prototype-"));
+  const path = join(privateTempDir, `${tempFileCounter++}.png`);
+
+  writeFileSync(path, png, { flag: "wx" });
+
+  return path;
+}
+
+function base64Transmit(png: Uint8Array, region: CellRegion, imageId: number): string {
+  const base64 = Buffer.from(png).toString("base64");
+  const controlKeys = `a=T,f=100,${placementKeys(imageId, region)}`;
+  let sequence = "";
+
+  for (let offset = 0; offset < base64.length; offset += CHUNK_BYTES) {
+    const chunk = base64.slice(offset, offset + CHUNK_BYTES);
+    const isMore = offset + CHUNK_BYTES < base64.length ? 1 : 0;
+
+    sequence +=
+      offset === 0
+        ? graphicsCommand(`${controlKeys},m=${isMore}`, chunk)
+        : graphicsCommand(`m=${isMore}`, chunk);
+  }
+
+  return sequence;
+}
+
+function fileTransmit(png: Uint8Array, region: CellRegion, imageId: number): string {
+  const path = writeTempPng(png);
+  const payload = Buffer.from(path).toString("base64");
+
+  return graphicsCommand(`a=T,f=100,t=t,${placementKeys(imageId, region)}`, payload);
+}
+
+/**
+ * Transmit a PNG and display it filling the region's cells (a=T). f=100 is PNG,
+ * C=1 keeps the cursor put so a full-region image cannot scroll the screen, and
+ * q=2 suppresses the terminal's replies. The whole write is bracketed in
+ * synchronized-update mode so the terminal composites it atomically. `file`
+ * hands over a temp path (t=t: the terminal deletes it after reading); `base64`
+ * inlines the data, chunked at 4096 bytes.
+ */
+export function transmitKittyImage(
+  write: OrderedWrite,
+  png: Uint8Array,
+  region: CellRegion,
+  imageId: number,
+  medium: TransmitMedium = "base64",
+): void {
+  if (region.columns < 1 || region.rows < 1) return;
+  const body =
+    medium === "file" ? fileTransmit(png, region, imageId) : base64Transmit(png, region, imageId);
+
+  write(SYNCHRONIZED_UPDATE_START + atRegion(region, body) + SYNCHRONIZED_UPDATE_END);
+}
+
+/** Re-place the already-transmitted image over its region, cheaply (a=p, no data). */
+export function placeKittyImage(write: OrderedWrite, region: CellRegion, imageId: number): void {
+  if (region.columns < 1 || region.rows < 1) return;
+  write(atRegion(region, graphicsCommand(`a=p,${placementKeys(imageId, region)}`, "")));
+}
+
+/** Remove the image so it does not linger after the sheet closes (a=d). */
+export function deleteKittyImage(write: OrderedWrite, imageId: number): void {
+  write(graphicsCommand(`a=d,d=i,i=${imageId},q=2`, ""));
+}

package/src/launch-layout.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test } from "bun:test";
+import {
+  defaultLayout,
+  layoutFromPanes,
+  pairLayout,
+  planLayout,
+  pullRequestReviewLayout,
+  reviewLayout,
+} from "./launch-layout";
+
+describe("launch layout factories", () => {
+  test("review opens the diff zoomed with the Changes panel", () => {
+    // Assert
+    expect(reviewLayout()).toEqual({ threads: true, rightSidebar: "changes", zoomChanges: true });
+  });
+
+  test("pair opens the Project tree focused beside a zoomed Changes editor", () => {
+    expect(pairLayout()).toEqual({
+      threads: true,
+      rightSidebar: "changes",
+      zoomChanges: true,
+      projectMode: "tree",
+      focusPane: "project",
+    });
+  });
+
+  test("pull request review keeps its brief beside the Changes panel", () => {
+    // Assert
+    expect(pullRequestReviewLayout()).toEqual({
+      threads: true,
+      rightSidebar: "changes",
+      zoomChanges: false,
+    });
+  });
+
+  test("plan fills the middle with the thread pane and no right region", () => {
+    // Assert
+    expect(planLayout()).toEqual({ threads: true, rightSidebar: "off", zoomChanges: false });
+  });
+
+  test("the first-run default lands on the inbox with the diff zoomed", () => {
+    // Assert
+    expect(defaultLayout()).toEqual({ threads: true, rightSidebar: "changes", zoomChanges: true });
+  });
+});
+
+describe("layoutFromPanes", () => {
+  test("the Changes editor wins the right region when open", () => {
+    // Assert
+    expect(
+      layoutFromPanes({ threads: true, changesOpen: true, projectOpen: true, zoomChanges: true }),
+    ).toEqual({ threads: true, rightSidebar: "changes", zoomChanges: true });
+  });
+
+  test("the Project tree holds the right region when the Changes editor is closed", () => {
+    // Assert
+    expect(
+      layoutFromPanes({
+        threads: false,
+        changesOpen: false,
+        projectOpen: true,
+        zoomChanges: false,
+      }),
+    ).toEqual({ threads: false, rightSidebar: "project", zoomChanges: false });
+  });
+
+  test("the right region is off when neither pane is open", () => {
+    // Assert
+    expect(
+      layoutFromPanes({
+        threads: true,
+        changesOpen: false,
+        projectOpen: false,
+        zoomChanges: false,
+      }),
+    ).toEqual({ threads: true, rightSidebar: "off", zoomChanges: false });
+  });
+});

package/src/launch-layout.ts

@@ -0,0 +1,62 @@
+/**
+ * The pane composition a launch opens with: whether the Threads sidebar is open,
+ * what the right region shows, and whether the Changes editor is zoomed. Each
+ * command picks a layout through a factory; a bare launch restores the last one
+ * the user left (persisted in config), falling back to the default.
+ */
+
+export interface LaunchLayout {
+  /** The Threads sidebar is open. */
+  threads: boolean;
+  /** The right region: the Changes editor, the Project tree, or closed. */
+  rightSidebar: "changes" | "project" | "off";
+  /** The Changes editor is zoomed - the Thread pane hides so the diff fills the middle. */
+  zoomChanges: boolean;
+  /** Which Project sidebar tab opens while the Changes editor stays visible. */
+  projectMode?: "changes" | "tree";
+  /** Keyboard focus when opening a selected Thread. */
+  focusPane?: "threads" | "thread" | "changes" | "project";
+}
+
+/** `cueloop diff`: the diff front and center. */
+export function reviewLayout(): LaunchLayout {
+  return { threads: true, rightSidebar: "changes", zoomChanges: true };
+}
+
+/** `cueloop pair`: browse project files beside the zoomed Changes editor. */
+export function pairLayout(): LaunchLayout {
+  return {
+    threads: true,
+    rightSidebar: "changes",
+    zoomChanges: true,
+    projectMode: "tree",
+    focusPane: "project",
+  };
+}
+
+/** `cueloop review <pr>`: PR context beside the Changes panel. */
+export function pullRequestReviewLayout(): LaunchLayout {
+  return { threads: true, rightSidebar: "changes", zoomChanges: false };
+}
+
+/** `cueloop plan` / `cueloop reply`: the thread pane fills the middle; no Changes panel. */
+export function planLayout(): LaunchLayout {
+  return { threads: true, rightSidebar: "off", zoomChanges: false };
+}
+
+/** The first-run default, before any layout has been remembered: the inbox with the diff zoomed. */
+export function defaultLayout(): LaunchLayout {
+  return { threads: true, rightSidebar: "changes", zoomChanges: true };
+}
+
+/** Read back the layout the panes currently sit in, to remember it for the next bare launch. */
+export function layoutFromPanes(panes: {
+  threads: boolean;
+  changesOpen: boolean;
+  projectOpen: boolean;
+  zoomChanges: boolean;
+}): LaunchLayout {
+  const rightSidebar = panes.changesOpen ? "changes" : panes.projectOpen ? "project" : "off";
+
+  return { threads: panes.threads, rightSidebar, zoomChanges: panes.zoomChanges };
+}

package/src/mark-runs.ts

@@ -0,0 +1,121 @@
+/**
+ * Mark geometry for an annotated line of text: which stretches are marked
+ * (a discussion span, a held selection) or carry the caret cell, the greedy
+ * word wrap into visual lines, and the printable-key test that starts a
+ * comment. Renderer-free, shared by the plan thread view and the diff sheet.
+ */
+
+import type { KeyEvent } from "@opentui/core";
+import { wordRanges } from "./thread-selection";
+
+export interface MarkRange {
+  start: number;
+  end: number;
+  /** The bare caret's single cell - a cursor, not yet a mark. */
+  caretOnly?: boolean;
+}
+
+export interface Run {
+  text: string;
+  marked: boolean;
+  caretOnly: boolean;
+}
+
+/** Split a block's text into plain/marked runs from the union of ranges. */
+export function runsFor(text: string, ranges: MarkRange[]): Run[] {
+  const cuts = new Set<number>([0, text.length]);
+
+  for (const range of ranges) {
+    cuts.add(Math.max(0, range.start));
+    cuts.add(Math.min(text.length, range.end));
+  }
+  const edges = [...cuts].toSorted((left, right) => left - right);
+  const runs: Run[] = [];
+
+  for (let index = 0; index < edges.length - 1; index++) {
+    const start = edges[index]!;
+    const end = edges[index + 1]!;
+
+    if (end <= start) continue;
+    const covering = ranges.filter((range) => range.start <= start && end <= range.end);
+    // the caret cell shows through a mark, so the head of a selection is visible
+    runs.push({
+      text: text.slice(start, end),
+      marked: covering.some((range) => range.caretOnly !== true),
+      caretOnly: covering.some((range) => range.caretOnly === true),
+    });
+  }
+
+  return runs.length > 0 ? runs : [{ text, marked: false, caretOnly: false }];
+}
+
+/** A visual line of a block: the char range of the block's text it shows. */
+export interface VisualLine {
+  start: number;
+  end: number;
+}
+
+/**
+ * Greedy word wrap into visual-line char ranges, so a comment card can slot
+ * in directly below the line its mark ends on (mid-paragraph when needed).
+ */
+export function wrapLines(text: string, width: number): VisualLine[] {
+  const lines: VisualLine[] = [];
+  let segmentStart = 0;
+
+  // hard breaks first: every visual line must be exactly one terminal row,
+  // or hit-testing and the mark geometry drift from what is painted
+  for (const segment of text.split("\n")) {
+    const segmentEnd = segmentStart + segment.length;
+
+    if (width <= 0 || segment.length <= width) {
+      lines.push({ start: segmentStart, end: segmentEnd });
+    } else {
+      // greedy word wrap inside the segment; the first line keeps its
+      // leading indentation, continuation lines start at a word
+      let lineStart = segmentStart;
+      let lineEnd = segmentStart;
+
+      for (const word of wordRanges(segment)) {
+        const wordStart = segmentStart + word.start;
+        const wordEnd = segmentStart + word.end;
+
+        if (wordEnd - lineStart > width && lineEnd > lineStart) {
+          lines.push({ start: lineStart, end: lineEnd });
+          lineStart = wordStart;
+        }
+        // a token wider than the line (a long identifier, a URL) breaks at the cell edge, so
+        // every visual line stays one terminal row and nothing is clipped away
+        while (wordEnd - lineStart > width) {
+          lines.push({ start: lineStart, end: lineStart + width });
+          lineStart += width;
+        }
+        lineEnd = wordEnd;
+      }
+      lines.push({ start: lineStart, end: Math.max(lineEnd, lineStart) });
+    }
+    segmentStart = segmentEnd + 1;
+  }
+
+  return lines;
+}
+
+/** The block's mark ranges clipped to one visual line, in that line's coordinates. */
+export function lineMarkRanges(ranges: MarkRange[], line: VisualLine): MarkRange[] {
+  return ranges
+    .map((range) => ({
+      start: Math.max(range.start, line.start) - line.start,
+      end: Math.min(range.end, line.end) - line.start,
+      caretOnly: range.caretOnly,
+    }))
+    .filter((range) => range.end > range.start);
+}
+
+/** Printable input that should reach a composer: one key, or a whole pasted run in one event. */
+export function printableSequence(key: KeyEvent): string | null {
+  if (!key.sequence || key.ctrl || key.meta) return null;
+  // reject any run carrying a control byte, so escape sequences and \r\t\b never seed a draft
+  for (const character of key.sequence) if (character < " ") return null;
+
+  return key.sequence.length > 0 ? key.sequence : null;
+}

package/src/markdown-editor-syntax-style.ts

@@ -0,0 +1,50 @@
+/**
+ * The native SyntaxStyle for the inline markdown editor: maps each markdown
+ * token group to a theme color and attribute set, and resolves the styleId the
+ * edit buffer needs for `addHighlightByCharRange`. Cached per theme, mirroring
+ * syntaxStyleFor. Syntax punctuation (the "marker" group) is dimmed rather than
+ * hidden, since the editor shows raw source.
+ */
+
+import { SyntaxStyle, type StyleDefinitionInput } from "@opentui/core";
+import { type Theme } from "./theme";
+import { MARKDOWN_HIGHLIGHT_GROUPS, type MarkdownHighlightGroup } from "./markdown-highlight";
+
+/** A markdown SyntaxStyle plus the lookup from token group to its native styleId. */
+export interface MarkdownEditorStyle {
+  style: SyntaxStyle;
+  styleIdFor: (group: MarkdownHighlightGroup) => number;
+}
+
+function markdownGroupStyles(theme: Theme): Record<MarkdownHighlightGroup, StyleDefinitionInput> {
+  return {
+    heading: { bold: true },
+    marker: { fg: theme.textDim },
+    link: { fg: theme.blue, underline: true },
+    code: { fg: theme.textDim },
+  };
+}
+
+const markdownEditorStyleCache = new WeakMap<Theme, MarkdownEditorStyle>();
+
+/** Build (or reuse) the markdown editor's SyntaxStyle for a theme, with a group-to-styleId lookup. */
+export function markdownEditorStyle(theme: Theme): MarkdownEditorStyle {
+  const cached = markdownEditorStyleCache.get(theme);
+
+  if (cached) return cached;
+  const groupStyles = markdownGroupStyles(theme);
+  const style = SyntaxStyle.fromStyles(groupStyles);
+  const styleIds = new Map<MarkdownHighlightGroup, number>();
+
+  for (const group of MARKDOWN_HIGHLIGHT_GROUPS) {
+    styleIds.set(group, style.getStyleId(group) ?? 0);
+  }
+  const entry: MarkdownEditorStyle = {
+    style,
+    styleIdFor: (group) => styleIds.get(group) ?? 0,
+  };
+
+  markdownEditorStyleCache.set(theme, entry);
+
+  return entry;
+}

package/src/markdown-grid.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+import {
+  layoutFrontmatterGrid,
+  layoutMarkdownTable,
+  parseFrontmatterRows,
+  parseMarkdownTable,
+} from "./markdown-grid";
+
+/** The plain text of a grid line, segments concatenated. */
+function lineText(line: { text: string }[]): string {
+  return line.map((segment) => segment.text).join("");
+}
+
+describe("parseMarkdownTable", () => {
+  test("reads header cells, alignments, and body rows", () => {
+    const table = parseMarkdownTable("| Name | Size |\n| :--- | ---: |\n| a | 1 |\n| bb | 22 |");
+
+    expect(table.header).toEqual(["Name", "Size"]);
+    expect(table.aligns).toEqual(["left", "right"]);
+    expect(table.rows).toEqual([
+      ["a", "1"],
+      ["bb", "22"],
+    ]);
+  });
+
+  test("center alignment reads from a :---: delimiter", () => {
+    expect(parseMarkdownTable("| a |\n| :---: |\n| x |").aligns).toEqual(["center"]);
+  });
+
+  test("an escaped pipe stays inside its cell instead of splitting the column", () => {
+    const table = parseMarkdownTable("| Name | Note |\n| --- | --- |\n| a | b \\| c |");
+
+    expect(table.rows).toEqual([["a", "b | c"]]);
+  });
+
+  test("a blank cell between border pipes survives the border strip", () => {
+    expect(parseMarkdownTable("|  | b |\n| --- | --- |\n| x | y |").header).toEqual(["", "b"]);
+  });
+});
+
+describe("layoutMarkdownTable", () => {
+  test("bolds the header, rules under it, and right-aligns a numeric column", () => {
+    const lines = layoutMarkdownTable(
+      parseMarkdownTable("| Name | Size |\n| --- | ---: |\n| a | 1 |"),
+    );
+
+    expect(lines[0]![0]!.bold).toBe(true);
+    expect(lineText(lines[0]!)).toBe("Name  Size");
+    expect(lines[1]![0]!.dim).toBe(true);
+    expect(lineText(lines[1]!)).toBe("─".repeat("Name  Size".length));
+    // "a" padded to the "Name" column, "1" right-aligned under "Size"
+    expect(lineText(lines[2]!)).toBe("a" + " ".repeat(8) + "1");
+  });
+});
+
+describe("parseFrontmatterRows", () => {
+  test("splits top-level key: value pairs", () => {
+    expect(parseFrontmatterRows("title: Plan\nowner: me")).toEqual([
+      { key: "title", value: "Plan" },
+      { key: "owner", value: "me" },
+    ]);
+  });
+
+  test("folds an indented continuation into the row above", () => {
+    expect(parseFrontmatterRows("tags:\n  - one\n  - two")).toEqual([
+      { key: "tags", value: "- one\n- two" },
+    ]);
+  });
+});
+
+describe("layoutFrontmatterGrid", () => {
+  test("draws a full border with a bold key and a rule between rows", () => {
+    const lines = layoutFrontmatterGrid(
+      [
+        { key: "title", value: "Plan" },
+        { key: "owner", value: "me" },
+      ],
+      40,
+    );
+
+    expect(lineText(lines[0]!).startsWith("┌")).toBe(true);
+    expect(lineText(lines.at(-1)!).startsWith("└")).toBe(true);
+    // the key cell is bold, the border pieces are dim
+    const firstRow = lines[1]!;
+
+    expect(firstRow.find((segment) => segment.text.includes("title"))!.bold).toBe(true);
+    expect(firstRow[0]!.dim).toBe(true);
+    // a divider separates the two rows
+    expect(lines.some((line) => lineText(line).startsWith("├"))).toBe(true);
+  });
+
+  test("wraps a long value across cell lines, keeping the key on the first", () => {
+    const lines = layoutFrontmatterGrid([{ key: "desc", value: "one two three four five" }], 24);
+    const bodyLines = lines.filter((line) => lineText(line).startsWith("│"));
+
+    expect(bodyLines.length).toBeGreaterThan(1);
+    expect(bodyLines[0]!.some((segment) => segment.text.includes("desc"))).toBe(true);
+    // the continuation line keeps the key column blank
+    expect(bodyLines[1]!.some((segment) => segment.text.includes("desc"))).toBe(false);
+  });
+});