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

package/src/mark-runs.ts

@@ -0,0 +1,120 @@
+/**
+ * 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);
+}
+
+/** A printable character: single-width input that should reach a composer. */
+export function printableSequence(key: KeyEvent): string | null {
+  const printable =
+    key.sequence && key.sequence.length === 1 && !key.ctrl && !key.meta && key.sequence >= " ";
+
+  return printable ? key.sequence : null;
+}

package/src/prototype-browser.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, test } from "bun:test";
+import { cssBoxToCell, imageCellToCss } from "./prototype-browser";
+
+const IMAGE = { x: 1, y: 1, width: 80, height: 40 };
+const VIEWPORT = { width: 1280, height: 720 };
+
+describe("imageCellToCss", () => {
+  test("maps a cell inside the image to the center of its viewport pixel band", () => {
+    // Act - the image's top-left cell (1,1)
+    const css = imageCellToCss({ x: 1, y: 1 }, IMAGE, VIEWPORT)!;
+
+    // Assert - half a cell into the first band
+    expect(css.x).toBeCloseTo((0.5 / 80) * 1280, 5);
+    expect(css.y).toBeCloseTo((0.5 / 40) * 720, 5);
+  });
+
+  test("a click below the image's origin lands deeper in the page", () => {
+    // Act
+    const top = imageCellToCss({ x: 40, y: 2 }, IMAGE, VIEWPORT)!;
+    const bottom = imageCellToCss({ x: 40, y: 38 }, IMAGE, VIEWPORT)!;
+
+    // Assert
+    expect(bottom.y).toBeGreaterThan(top.y);
+  });
+
+  test("a cell outside the image returns null", () => {
+    // Assert - the gutter left of and the row above the image
+    expect(imageCellToCss({ x: 0, y: 10 }, IMAGE, VIEWPORT)).toBeNull();
+    expect(imageCellToCss({ x: 10, y: 0 }, IMAGE, VIEWPORT)).toBeNull();
+    expect(imageCellToCss({ x: 200, y: 10 }, IMAGE, VIEWPORT)).toBeNull();
+  });
+});
+
+describe("cssBoxToCell", () => {
+  test("maps a viewport rect back to the image cells covering it", () => {
+    // Arrange - a rect covering the right half, lower half of the page
+    const box = { x: 640, y: 360, width: 320, height: 180 };
+
+    // Act
+    const cell = cssBoxToCell(box, IMAGE, VIEWPORT);
+
+    // Assert - x at half width -> 40 cells in from the image origin (1)
+    expect(cell.column).toBe(1 + Math.floor((640 / 1280) * 80));
+    expect(cell.row).toBe(1 + Math.floor((360 / 720) * 40));
+    expect(cell.columns).toBe(Math.round((320 / 1280) * 80));
+    expect(cell.rows).toBe(Math.round((180 / 720) * 40));
+  });
+
+  test("a zero-size rect still reserves at least one cell", () => {
+    // Assert
+    const cell = cssBoxToCell({ x: 0, y: 0, width: 0, height: 0 }, IMAGE, VIEWPORT);
+
+    expect(cell.columns).toBe(1);
+    expect(cell.rows).toBe(1);
+  });
+});

package/src/prototype-browser.ts

@@ -0,0 +1,307 @@
+/// <reference lib="dom" />
+/**
+ * Headless-Chromium backing for prototype review: render an HTML file to a PNG
+ * and resolve a click coordinate to a DOM element. puppeteer-core is imported
+ * lazily so plan/diff review and the test suite never load it.
+ */
+
+export interface PrototypeElement {
+  /** Stable CSS selector - the annotation anchor's authority. */
+  selector: string;
+  /** Short human label for the rail card (element text, else the selector). */
+  quote: string;
+  /** Element rectangle in CSS pixels within the captured viewport. */
+  box: ElementBox;
+}
+
+export interface ElementBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface PrototypeViewport {
+  width: number;
+  height: number;
+}
+
+export interface PrototypeRenderer {
+  readonly viewport: PrototypeViewport;
+  screenshot(): Promise<Uint8Array>;
+  elementAt(cssX: number, cssY: number): Promise<PrototypeElement | null>;
+  /** Scroll the page by a pixel delta; returns whether the scroll position moved. */
+  scrollBy(deltaY: number): Promise<boolean>;
+  close(): Promise<void>;
+}
+
+export interface LaunchOptions {
+  filePath: string;
+  viewport: PrototypeViewport;
+  /** Capture density; 1 when the viewport already matches the region's pixels. */
+  deviceScaleFactor?: number;
+  /** Absolute path to a Chrome/Chromium binary; falls back to the channel. */
+  executablePath?: string;
+  /** The terminal's color scheme, emulated as prefers-color-scheme so a mockup
+   *  with theme-aware CSS renders to match the surface it emerges into. */
+  colorScheme?: "dark" | "light";
+}
+
+/** Cell click -> CSS pixel inside the letterboxed image, or null when outside it. */
+export function imageCellToCss(
+  event: { x: number; y: number },
+  image: { x: number; y: number; width: number; height: number },
+  viewport: PrototypeViewport,
+): { x: number; y: number } | null {
+  const columnInImage = event.x - image.x;
+  const rowInImage = event.y - image.y;
+
+  if (
+    columnInImage < 0 ||
+    rowInImage < 0 ||
+    columnInImage >= image.width ||
+    rowInImage >= image.height
+  ) {
+    return null;
+  }
+
+  return {
+    x: ((columnInImage + 0.5) / image.width) * viewport.width,
+    y: ((rowInImage + 0.5) / image.height) * viewport.height,
+  };
+}
+
+/** CSS pixel rect -> the image cell it maps to, for anchoring overlays. */
+export function cssBoxToCell(
+  box: ElementBox,
+  image: { x: number; y: number; width: number; height: number },
+  viewport: PrototypeViewport,
+) {
+  const scaleColumn = image.width / viewport.width;
+  const scaleRow = image.height / viewport.height;
+
+  return {
+    column: image.x + Math.floor(box.x * scaleColumn),
+    row: image.y + Math.floor(box.y * scaleRow),
+    columns: Math.max(1, Math.round(box.width * scaleColumn)),
+    rows: Math.max(1, Math.round(box.height * scaleRow)),
+  };
+}
+
+export type PrototypeRendererFactory = (options: LaunchOptions) => Promise<PrototypeRenderer>;
+
+let rendererFactory: PrototypeRendererFactory | null = null;
+
+/** Override the renderer factory so tests can inject a browserless fake. */
+export function setPrototypeRendererFactory(factory: PrototypeRendererFactory | null): void {
+  rendererFactory = factory;
+}
+
+/** The active factory - the injected fake in tests, else real headless Chromium. */
+export function prototypeRendererFactory(): PrototypeRendererFactory {
+  return rendererFactory ?? launchPrototypeRenderer;
+}
+
+type PuppeteerBrowser = Awaited<ReturnType<typeof import("puppeteer-core").default.launch>>;
+
+// One Chromium per process, kept warm and reused across prototype opens: the
+// launch is the dominant load cost, so each open only spawns a fresh page.
+let sharedBrowser: Promise<PuppeteerBrowser> | null = null;
+
+async function warmBrowser(executablePath: string | undefined): Promise<PuppeteerBrowser> {
+  // reuse the warm browser only while it is still connected; a crashed or
+  // disconnected Chromium is dropped so the next open relaunches instead of
+  // calling newPage on a dead process forever
+  const cached = sharedBrowser ? await sharedBrowser.catch(() => null) : null;
+
+  if (cached && cached.connected) return cached;
+  const puppeteer = (await import("puppeteer-core")).default;
+  const launched = puppeteer.launch({
+    executablePath: executablePath ?? chromeExecutable(),
+    headless: true,
+    args: ["--no-sandbox", "--hide-scrollbars", "--force-color-profile=srgb"],
+  });
+
+  sharedBrowser = launched;
+  const browser = await launched.catch((error) => {
+    if (sharedBrowser === launched) sharedBrowser = null;
+    throw error;
+  });
+
+  browser.once("disconnected", () => {
+    if (sharedBrowser === launched) sharedBrowser = null;
+  });
+
+  return browser;
+}
+
+export async function launchPrototypeRenderer(options: LaunchOptions): Promise<PrototypeRenderer> {
+  const { pathToFileURL } = await import("node:url");
+  const browser = await warmBrowser(options.executablePath);
+  // close only the page on teardown, never the shared browser, so the next open
+  // reuses the warm Chromium
+  const page = await browser.newPage();
+
+  try {
+    await page.setViewport({
+      width: options.viewport.width,
+      height: options.viewport.height,
+      deviceScaleFactor: options.deviceScaleFactor ?? 2,
+    });
+    // match the terminal's scheme so a theme-aware mockup renders its dark or
+    // light variant to sit correctly on the surface it emerges into
+    await page.emulateMediaFeatures([
+      { name: "prefers-color-scheme", value: options.colorScheme ?? "light" },
+    ]);
+    // `load` waits for images and styles but skips networkidle0's fixed 500ms
+    // idle window, which a static local file would otherwise always pay
+    await page.goto(pathToFileURL(options.filePath).href, { waitUntil: "load" });
+    // Render the mockup on the terminal's own surface rather than on an opaque
+    // page: strip the root background so it never paints a square box, and the
+    // capture (taken with alpha, below) lets the active terminal theme show
+    // through around the mockup's own components - the prototype emerges into
+    // whatever theme is running instead of sitting in a grey card.
+    await page.evaluate(() => {
+      for (const element of [document.documentElement, document.body]) {
+        element?.style.setProperty("background", "transparent", "important");
+      }
+    });
+  } catch (error) {
+    await page.close().catch(() => undefined);
+    throw error;
+  }
+
+  return {
+    viewport: options.viewport,
+    async screenshot() {
+      // omitBackground keeps the alpha from the stripped page background, so the
+      // terminal composites the mockup over its own theme surface.
+      const buffer = await page.screenshot({
+        type: "png",
+        encoding: "binary",
+        omitBackground: true,
+      });
+
+      return new Uint8Array(buffer);
+    },
+    async elementAt(cssX, cssY) {
+      return page.evaluate(elementAtScript, cssX, cssY);
+    },
+    async scrollBy(deltaY) {
+      return page.evaluate(scrollByScript, deltaY);
+    },
+    async close() {
+      await page.close().catch(() => undefined);
+    },
+  };
+}
+
+/** Serialized into the page (self-contained for puppeteer): resolve the click to a component element. */
+function elementAtScript(x: number, y: number) {
+  const SEMANTIC = new Set([
+    "SECTION",
+    "ARTICLE",
+    "LI",
+    "NAV",
+    "HEADER",
+    "FOOTER",
+    "ASIDE",
+    "FORM",
+  ]);
+  const isNamed = (element: Element): boolean =>
+    element.classList.length > 0 || SEMANTIC.has(element.tagName);
+  // a card wraps several children: climb to the nearest named container holding
+  // more than one child, else the nearest named ancestor, else the clicked leaf
+  const componentRoot = (start: Element): Element => {
+    let namedFallback: Element | null = null;
+    let current: Element | null = start;
+
+    while (current && current !== document.body) {
+      if (isNamed(current)) {
+        if (current.childElementCount > 1) return current;
+        namedFallback = namedFallback ?? current;
+      }
+      current = current.parentElement;
+    }
+
+    return namedFallback ?? start;
+  };
+  const selectorFor = (start: Element): string => {
+    const parts: string[] = [];
+    let current: Element | null = start;
+
+    while (current && current.nodeType === 1 && current !== document.documentElement) {
+      let part = current.tagName.toLowerCase();
+
+      if (current.id) {
+        parts.unshift(part + "#" + CSS.escape(current.id));
+        break;
+      }
+      const parent: Element | null = current.parentElement;
+
+      if (parent) {
+        const currentTagName = current.tagName;
+        const twins = [...parent.children].filter((child) => child.tagName === currentTagName);
+
+        if (twins.length > 1) part += ":nth-of-type(" + (twins.indexOf(current) + 1) + ")";
+      }
+      parts.unshift(part);
+      current = current.parentElement;
+    }
+
+    return parts.join(" > ");
+  };
+  // Prefer the nearest focusable target before falling back to its component container.
+  const focusableTarget = (start: Element | null): Element | null => {
+    for (
+      let element: Element | null = start;
+      element && element !== document.body;
+      element = element.parentElement
+    ) {
+      if (element instanceof HTMLElement && element.tabIndex >= 0) {
+        return element;
+      }
+    }
+
+    return null;
+  };
+  const hit = document.elementFromPoint(x, y);
+
+  if (!(hit instanceof Element)) return null;
+  const node = focusableTarget(hit) ?? componentRoot(hit);
+  const selector = selectorFor(node);
+
+  if (!selector) return null;
+  const text = (node.textContent || "").replace(/\s+/g, " ").trim();
+  const tag = node.tagName.toLowerCase();
+  const quote = text
+    ? text.slice(0, 80)
+    : node.id
+      ? tag + "#" + node.id
+      : node.classList.length
+        ? tag + "." + node.classList[0]
+        : tag;
+  const rect = node.getBoundingClientRect();
+
+  return { selector, quote, box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height } };
+}
+
+function scrollByScript(deltaY: number): boolean {
+  const before = window.scrollY;
+
+  window.scrollBy(0, deltaY);
+
+  return window.scrollY !== before;
+}
+
+/** Standard Chrome install locations by platform; puppeteer-core ships no browser. */
+function chromeExecutable(): string {
+  if (process.platform === "darwin") {
+    return "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+  }
+  if (process.platform === "win32") {
+    return "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe";
+  }
+
+  return "/usr/bin/google-chrome";
+}

package/src/prototype-pixels.tsx

@@ -0,0 +1,35 @@
+/**
+ * Lazy boundary for the opt-in kitty pixel prototype. The pixel path pulls in the
+ * kitty image writer, the headless-browser renderer, and (on first paint) puppeteer;
+ * none of that belongs in the runtime unless the `[experimental] prototype_pixels`
+ * flag is on. Importing only the TYPE here is erased at build time, so the real
+ * module - and its dependencies - loads only when this component actually mounts,
+ * which App does exclusively for a pixel prototype. This lives outside components/
+ * on purpose: it is an app boundary, not a visual component the story catalog covers.
+ */
+
+import React, { useEffect, useState } from "react";
+import type { PrototypeContentViewProps } from "./components/PrototypeContentView";
+
+type PixelPrototypeView =
+  (typeof import("./components/PrototypeContentView"))["PrototypeContentView"];
+
+export function PrototypePixels(props: PrototypeContentViewProps): React.ReactNode {
+  const [View, setView] = useState<PixelPrototypeView | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+
+    void import("./components/PrototypeContentView").then((module) => {
+      if (alive) setView(() => module.PrototypeContentView);
+    });
+
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  if (!View) return null;
+
+  return <View {...props} />;
+}

package/src/pty.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { ptyAvailable, spawn } from "./pty";
+
+// The forkpty shim is a per-platform prebuilt; skip where none ships (e.g. CI
+// without the built dylib), exactly as the caller degrades to a herdr split.
+const ptyTest = ptyAvailable() ? test : test.skip;
+
+/** Run a child on a PTY, collect its output, and resolve with the exit code. */
+function runOnPty(file: string, args: string[]): Promise<{ output: string; exitCode: number }> {
+  return new Promise((resolve, reject) => {
+    const pty = spawn(file, args, { name: "xterm-256color", cols: 80, rows: 24 });
+    let output = "";
+    const timeout = setTimeout(() => reject(new Error("pty child never exited")), 5000);
+
+    pty.onData((chunk) => {
+      output += chunk;
+    });
+    pty.onExit(({ exitCode }) => {
+      clearTimeout(timeout);
+      resolve({ output, exitCode });
+    });
+  });
+}
+
+describe("pty", () => {
+  ptyTest("streams a child's output and reports its exit code", async () => {
+    // Act
+    const { output, exitCode } = await runOnPty("sh", ["-c", "printf 'PTY-OK'; exit 7"]);
+
+    // Assert
+    expect(output).toContain("PTY-OK");
+    expect(exitCode).toBe(7);
+  });
+
+  ptyTest("forwards written input to the child", async () => {
+    // Arrange - `cat` echoes stdin back through the tty until it closes
+    const pty = spawn("cat", [], { name: "xterm-256color", cols: 80, rows: 24 });
+    let output = "";
+
+    pty.onData((chunk) => {
+      output += chunk;
+    });
+
+    // Act
+    pty.write("ping\n");
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    pty.kill();
+
+    // Assert - the tty echoes the written line back
+    expect(output).toContain("ping");
+  });
+
+  ptyTest("passes env through to the child", async () => {
+    // Act
+    const { output } = await runOnPty("sh", ["-c", "printf '%s' \"$CUELOOP_PTY_MARKER\""]);
+
+    // Assert - a child with no inherited marker prints nothing for it
+    expect(output).not.toContain("marker-value");
+
+    // Act - now inject the marker via env
+    const withEnv = await new Promise<string>((resolve, reject) => {
+      const pty = spawn("sh", ["-c", "printf '%s' \"$CUELOOP_PTY_MARKER\""], {
+        name: "xterm-256color",
+        env: { ...process.env, CUELOOP_PTY_MARKER: "marker-value" },
+      });
+      let collected = "";
+      const timeout = setTimeout(() => reject(new Error("no exit")), 5000);
+
+      pty.onData((chunk) => {
+        collected += chunk;
+      });
+      pty.onExit(() => {
+        clearTimeout(timeout);
+        resolve(collected);
+      });
+    });
+
+    // Assert
+    expect(withEnv).toContain("marker-value");
+  });
+});