@cueloop/client 0.1.0-alpha.5 → 0.1.0-alpha.51

package/src/prototype-browser.ts

@@ -0,0 +1,243 @@
+/// <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>;
+  highlight(selector: string | null): Promise<void>;
+  /** 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;
+  /** Absolute path to a Chrome/Chromium binary; falls back to the channel. */
+  executablePath?: string;
+}
+
+/** 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,
+): { column: number; row: number; columns: number; rows: number } {
+  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;
+}
+
+export async function launchPrototypeRenderer(options: LaunchOptions): Promise<PrototypeRenderer> {
+  const puppeteer = (await import("puppeteer-core")).default;
+  const { pathToFileURL } = await import("node:url");
+  const browser = await puppeteer.launch({
+    executablePath: options.executablePath ?? chromeExecutable(),
+    headless: true,
+    args: ["--no-sandbox", "--hide-scrollbars", "--force-color-profile=srgb"],
+    defaultViewport: {
+      width: options.viewport.width,
+      height: options.viewport.height,
+      deviceScaleFactor: 2,
+    },
+  });
+  // close the browser if page setup fails, so a launch error never leaks Chromium
+  const page = await browser.newPage().catch(async (error) => {
+    await browser.close();
+    throw error;
+  });
+  await page
+    .goto(pathToFileURL(options.filePath).href, { waitUntil: "networkidle0" })
+    .catch(async (error) => {
+      await browser.close();
+      throw error;
+    });
+
+  return {
+    viewport: options.viewport,
+    async screenshot() {
+      const buffer = await page.screenshot({ type: "png", encoding: "binary" });
+      return new Uint8Array(buffer as Buffer);
+    },
+    async elementAt(cssX, cssY) {
+      return (await page.evaluate(elementAtScript, cssX, cssY)) as PrototypeElement | null;
+    },
+    async highlight(selector) {
+      await page.evaluate(highlightScript, selector);
+    },
+    async scrollBy(deltaY) {
+      return (await page.evaluate(scrollByScript, deltaY)) as boolean;
+    },
+    async close() {
+      await browser.close();
+    },
+  };
+}
+
+/** Serialized into the page (self-contained for puppeteer): resolve the click to a component element. */
+function elementAtScript(x: number, y: number): unknown {
+  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 twins = [...parent.children].filter((child) => child.tagName === current!.tagName);
+        if (twins.length > 1) part += ":nth-of-type(" + (twins.indexOf(current) + 1) + ")";
+      }
+      parts.unshift(part);
+      current = current.parentElement;
+    }
+    return parts.join(" > ");
+  };
+  const hit = document.elementFromPoint(x, y);
+  if (!(hit instanceof Element)) return null;
+  const node = 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;
+}
+
+function highlightScript(selector: string | null): void {
+  const ATTRIBUTE = "data-cueloop-selected";
+  const STYLE_ID = "cueloop-highlight-style";
+  document
+    .querySelectorAll("[" + ATTRIBUTE + "]")
+    .forEach((node) => node.removeAttribute(ATTRIBUTE));
+  if (!document.getElementById(STYLE_ID)) {
+    const style = document.createElement("style");
+    style.id = STYLE_ID;
+    style.textContent =
+      "[" + ATTRIBUTE + "]{outline:2px solid #f38ba8 !important;outline-offset:2px;}";
+    document.head.appendChild(style);
+  }
+  if (selector) {
+    const node = document.querySelector(selector);
+    if (node) node.setAttribute(ATTRIBUTE, "");
+  }
+}
+
+/** 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/pty.test.ts

@@ -0,0 +1,78 @@
+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");
+  });
+});

package/src/pty.ts

@@ -0,0 +1,222 @@
+/**
+ * A pseudo-terminal for the embedded Agent-tab terminal, over cueloop's own
+ * forkpty(3) FFI shim (native/src/pty.zig). `spawn` returns a `Pty` with
+ * `onData`/`onExit` events and `write`/`resize`/`kill`; a poll loop drains the
+ * child's output and decodes it as streaming UTF-8. `ptyAvailable()` returns
+ * false when no prebuilt shim ships for this platform, so callers fall back to a
+ * herdr split, exactly like the Ghostty VT loader.
+ */
+
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const DEFAULT_COLS = 80;
+const DEFAULT_ROWS = 24;
+/** How long the read loop sleeps when the child produced no output this tick. */
+const READ_IDLE_MS = 8;
+const READ_BUFFER_BYTES = 4096;
+/** cueloop_pty_read's sentinel: the child has exited and its output is drained. */
+const CHILD_EXITED = -2;
+
+export interface PtyForkOptions {
+  name?: string;
+  cols?: number;
+  rows?: number;
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface ExitEvent {
+  exitCode: number;
+}
+
+export interface Disposable {
+  dispose(): void;
+}
+
+/** The pseudo-terminal surface the embedded terminal consumes. */
+export interface IPty {
+  readonly pid: number;
+  readonly cols: number;
+  readonly rows: number;
+  readonly onData: (listener: (data: string) => void) => Disposable;
+  readonly onExit: (listener: (event: ExitEvent) => void) => Disposable;
+  write(data: string): void;
+  resize(cols: number, rows: number): void;
+  kill(signal?: string): void;
+}
+
+const PTY_SYMBOLS = {
+  cueloop_pty_spawn: {
+    args: [FFIType.ptr, FFIType.cstring, FFIType.ptr, FFIType.i32, FFIType.i32],
+    returns: FFIType.i32,
+  },
+  cueloop_pty_write: { args: [FFIType.i32, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_read: { args: [FFIType.i32, FFIType.ptr, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_resize: { args: [FFIType.i32, FFIType.i32, FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_kill: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_get_pid: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_get_exit_code: { args: [FFIType.i32], returns: FFIType.i32 },
+  cueloop_pty_close: { args: [FFIType.i32], returns: FFIType.void },
+} as const;
+
+type PtyLib = ReturnType<typeof dlopen<typeof PTY_SYMBOLS>>["symbols"];
+
+/** The prebuilt pty shim for this platform, or null when none ships for it. */
+function nativeLibraryPath(): string | null {
+  const suffix = process.platform === "darwin" ? "dylib" : "so";
+  const dir = `${process.platform}-${process.arch}`;
+  const path = join(import.meta.dir, "..", "native", dir, `libcuelooppty.${suffix}`);
+  return existsSync(path) ? path : null;
+}
+
+/** One shared load of the pty shim; null when no dylib ships for the platform. */
+let ptyLib: PtyLib | null | undefined;
+function library(): PtyLib | null {
+  if (ptyLib !== undefined) return ptyLib;
+  const path = nativeLibraryPath();
+  if (!path) return (ptyLib = null);
+  try {
+    ptyLib = dlopen(path, PTY_SYMBOLS).symbols;
+  } catch (error) {
+    console.error(`cueloop: failed to load ${path}:`, error);
+    ptyLib = null;
+  }
+  return ptyLib;
+}
+
+/** True when this platform ships a prebuilt pty shim (embedding is possible). */
+export function ptyAvailable(): boolean {
+  return library() !== null;
+}
+
+class EventEmitter<T> {
+  private listeners: ((value: T) => void)[] = [];
+  readonly event = (listener: (value: T) => void): Disposable => {
+    this.listeners.push(listener);
+    return {
+      dispose: () => {
+        const index = this.listeners.indexOf(listener);
+        if (index !== -1) this.listeners.splice(index, 1);
+      },
+    };
+  };
+  fire(value: T): void {
+    for (const listener of this.listeners) listener(value);
+  }
+}
+
+/** Pack tokens into the C shim's "tok\0tok\0...\0\0" (double-NUL-terminated) form. */
+function packTokens(tokens: string[]): Buffer {
+  return Buffer.from(tokens.map((token) => `${token}\0`).join("") + "\0", "utf8");
+}
+
+class Pty implements IPty {
+  private handle: number;
+  private processId: number;
+  private columns: number;
+  private rowCount: number;
+  private closing = false;
+  private reading = false;
+  private readonly decoder = new TextDecoder("utf-8");
+  private readonly dataEvent = new EventEmitter<string>();
+  private readonly exitEvent = new EventEmitter<ExitEvent>();
+
+  constructor(
+    private readonly lib: PtyLib,
+    file: string,
+    args: string[],
+    options: PtyForkOptions,
+  ) {
+    this.columns = options.cols ?? DEFAULT_COLS;
+    this.rowCount = options.rows ?? DEFAULT_ROWS;
+    const cwd = options.cwd ?? process.cwd();
+    const env = options.env
+      ? Object.entries(options.env).map(([key, value]) => `${key}=${value}`)
+      : [];
+
+    const argvPacked = packTokens([file, ...args]);
+    const envPacked = packTokens(env);
+    this.handle = lib.cueloop_pty_spawn(
+      ptr(argvPacked),
+      Buffer.from(`${cwd}\0`, "utf8"),
+      ptr(envPacked),
+      this.columns,
+      this.rowCount,
+    );
+    if (this.handle < 0) throw new Error("PTY spawn failed");
+    this.processId = lib.cueloop_pty_get_pid(this.handle);
+    // Let the caller attach onData/onExit before the first bytes arrive.
+    queueMicrotask(() => void this.readLoop());
+  }
+
+  get pid(): number {
+    return this.processId;
+  }
+  get cols(): number {
+    return this.columns;
+  }
+  get rows(): number {
+    return this.rowCount;
+  }
+  get onData() {
+    return this.dataEvent.event;
+  }
+  get onExit() {
+    return this.exitEvent.event;
+  }
+
+  write(data: string): void {
+    if (this.closing) return;
+    const buffer = Buffer.from(data, "utf8");
+    this.lib.cueloop_pty_write(this.handle, ptr(buffer), buffer.length);
+  }
+
+  resize(cols: number, rows: number): void {
+    if (this.closing) return;
+    this.columns = cols;
+    this.rowCount = rows;
+    this.lib.cueloop_pty_resize(this.handle, cols, rows);
+  }
+
+  kill(): void {
+    if (this.closing) return;
+    this.closing = true;
+    this.lib.cueloop_pty_kill(this.handle);
+    this.lib.cueloop_pty_close(this.handle);
+    this.exitEvent.fire({ exitCode: 0 });
+  }
+
+  private async readLoop(): Promise<void> {
+    if (this.reading) return;
+    this.reading = true;
+    const buffer = Buffer.allocUnsafe(READ_BUFFER_BYTES);
+    while (!this.closing) {
+      const count = this.lib.cueloop_pty_read(this.handle, ptr(buffer), buffer.length);
+      if (count > 0) {
+        // Stream mode buffers a multibyte char split across reads (box-drawing etc.).
+        const text = this.decoder.decode(buffer.subarray(0, count), { stream: true });
+        if (text) this.dataEvent.fire(text);
+      } else if (count === CHILD_EXITED || count < 0) {
+        // Both the drained-exit sentinel and a hard read error end the session:
+        // flush the decoder, reap for the code, close, and fire the exit once.
+        const tail = this.decoder.decode();
+        if (tail) this.dataEvent.fire(tail);
+        const exitCode = this.lib.cueloop_pty_get_exit_code(this.handle);
+        this.lib.cueloop_pty_close(this.handle);
+        this.closing = true;
+        this.exitEvent.fire({ exitCode });
+      } else {
+        await new Promise((resolve) => setTimeout(resolve, READ_IDLE_MS));
+      }
+    }
+  }
+}
+
+/** Spawn `file` with `args` on a fresh PTY. Throws when no shim ships (gate on ptyAvailable). */
+export function spawn(file: string, args: string[], options: PtyForkOptions = {}): IPty {
+  const lib = library();
+  if (!lib) throw new Error("cueloop: no pty shim for this platform");
+  return new Pty(lib, file, args, options);
+}

package/src/review-panel.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+import {
+  REVIEW_DEFAULT_WIDTH,
+  REVIEW_MAX_WIDTH,
+  REVIEW_MIN_WIDTH,
+  REVIEW_PLAN_MIN_WIDTH,
+  REVIEW_RESIZE_STEP,
+  clampWidth,
+  cycleReviewPanelMode,
+  maxWidthForTerminal,
+  resolveReviewWidth,
+  reviewRowsToDivider,
+  toggleReviewPanelMode,
+  widthFromMouseColumn,
+} from "./review-panel";
+
+describe("clampWidth", () => {
+  test("keeps a width inside the bounds untouched", () => {
+    expect(clampWidth(REVIEW_DEFAULT_WIDTH)).toBe(REVIEW_DEFAULT_WIDTH);
+  });
+
+  test("clamps below the minimum and above the maximum", () => {
+    expect(clampWidth(REVIEW_MIN_WIDTH - 10)).toBe(REVIEW_MIN_WIDTH);
+    expect(clampWidth(REVIEW_MAX_WIDTH + 10)).toBe(REVIEW_MAX_WIDTH);
+  });
+
+  test("rounds a fractional column to a whole one", () => {
+    expect(clampWidth(30.7)).toBe(31);
+  });
+
+  test("honors explicit bounds", () => {
+    expect(clampWidth(100, 10, 20)).toBe(20);
+    expect(clampWidth(5, 10, 20)).toBe(10);
+  });
+});
+
+describe("cycleReviewPanelMode", () => {
+  test("cycles expanded -> compact -> hidden -> expanded", () => {
+    expect(cycleReviewPanelMode("expanded")).toBe("compact");
+    expect(cycleReviewPanelMode("compact")).toBe("hidden");
+    expect(cycleReviewPanelMode("hidden")).toBe("expanded");
+  });
+});
+
+describe("toggleReviewPanelMode", () => {
+  test("the chevron toggles only between expanded and compact, never hidden", () => {
+    expect(toggleReviewPanelMode("expanded")).toBe("compact");
+    expect(toggleReviewPanelMode("compact")).toBe("expanded");
+    // a hidden panel has no chevron; a stray toggle still opens it
+    expect(toggleReviewPanelMode("hidden")).toBe("expanded");
+  });
+});
+
+describe("widthFromMouseColumn", () => {
+  test("measures the rail from the mouse column to the right edge", () => {
+    // divider dragged to column 80 of a 120-wide terminal -> a 40-col rail
+    expect(widthFromMouseColumn(80, 120)).toBe(40);
+  });
+
+  test("clamps the dragged width to the bounds", () => {
+    expect(widthFromMouseColumn(0, 120)).toBe(REVIEW_MAX_WIDTH);
+    expect(widthFromMouseColumn(119, 120)).toBe(REVIEW_MIN_WIDTH);
+  });
+
+  test("cannot drag the rail wide enough to starve the plan on a narrow terminal", () => {
+    // dragging to the far left edge of a 60-col terminal still leaves the plan its minimum
+    expect(widthFromMouseColumn(0, 60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+
+  test("the resize step widens and narrows within the clamp", () => {
+    expect(clampWidth(REVIEW_DEFAULT_WIDTH + REVIEW_RESIZE_STEP)).toBe(
+      REVIEW_DEFAULT_WIDTH + REVIEW_RESIZE_STEP,
+    );
+    expect(clampWidth(REVIEW_MIN_WIDTH - REVIEW_RESIZE_STEP)).toBe(REVIEW_MIN_WIDTH);
+  });
+});
+
+describe("maxWidthForTerminal", () => {
+  test("allows the full rail on a wide terminal", () => {
+    expect(maxWidthForTerminal(120)).toBe(REVIEW_MAX_WIDTH);
+  });
+
+  test("reserves the plan its minimum on a narrow terminal", () => {
+    // 60-col terminal: 30 for the plan and 1 for the divider leaves 29 for the rail
+    expect(maxWidthForTerminal(60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+
+  test("never drops below the rail minimum, however narrow the terminal", () => {
+    expect(maxWidthForTerminal(40)).toBe(REVIEW_MIN_WIDTH);
+  });
+});
+
+describe("resolveReviewWidth", () => {
+  test("leaves a width that already fits untouched", () => {
+    expect(resolveReviewWidth(REVIEW_DEFAULT_WIDTH, 120)).toBe(REVIEW_DEFAULT_WIDTH);
+  });
+
+  test("shrinks a wide persisted width so the plan keeps its room", () => {
+    // a saved 50-col rail on a 60-col terminal would leave the plan 9 cols; clamp it back
+    expect(resolveReviewWidth(REVIEW_MAX_WIDTH, 60)).toBe(60 - REVIEW_PLAN_MIN_WIDTH - 1);
+  });
+});
+
+describe("reviewRowsToDivider", () => {
+  test("builds one vertical glyph per row", () => {
+    expect(reviewRowsToDivider(3)).toBe("│\n│\n│");
+  });
+
+  test("never collapses to an empty column", () => {
+    expect(reviewRowsToDivider(0)).toBe("│");
+    expect(reviewRowsToDivider(-4)).toBe("│");
+  });
+});