@cueloop/client 0.1.0-alpha.67 → 0.1.0-alpha.69

package/src/components/{diff-sheet-layout.ts → diff-content-view-layout.ts}

@@ -1,7 +1,7 @@
 /**
  * Pure color logic for the diff review sheet, split out so it can be tested
  * without rendering: a row's colored spans (syntax under the intra-line change
- * color). DiffSheet.tsx paints marks and the caret over these per character.
+ * color). DiffContentView.tsx paints marks and the caret over these per character.
  */
 
 import type { Theme } from "../theme";

package/src/config.test.ts

@@ -126,19 +126,32 @@ describe("loadConfig", () => {
     }
   });
 
-  test("[ui] diff_view defaults to unified and parses split", () => {
+  test("[ui] diff_view defaults to split and parses stacked", () => {
     // Arrange
     const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-diff-"));
     const path = join(dir, "config.toml");
 
-    writeFileSync(path, `[ui]\ndiff_view = "split"\n`);
+    writeFileSync(path, `[ui]\ndiff_view = "stacked"\n`);
 
     try {
       // Assert
-      expect(loadConfig({ userConfigPath: "/nonexistent/config.toml" }).ui.diffView).toBe(
-        "unified",
-      );
-      expect(loadConfig({ userConfigPath: path }).ui.diffView).toBe("split");
+      expect(loadConfig({ userConfigPath: "/nonexistent/config.toml" }).ui.diffView).toBe("split");
+      expect(loadConfig({ userConfigPath: path }).ui.diffView).toBe("stacked");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('[ui] diff_view loads the pre-rename "unified" value as "stacked"', () => {
+    // Arrange - an upgrade must not flip a user who had persisted the old spelling
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg-diff-"));
+    const path = join(dir, "config.toml");
+
+    writeFileSync(path, `[ui]\ndiff_view = "unified"\n`);
+
+    try {
+      // Assert
+      expect(loadConfig({ userConfigPath: path }).ui.diffView).toBe("stacked");
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }

package/src/config.ts

@@ -26,8 +26,9 @@ export interface IntegrationsConfig {
 /** Post-submit behavior: "off" prompts, 0 closes instantly, N counts down. */
 export type AutoClose = "off" | number;
 
-/** How the Changes diff renders: one inline column, or old|new side by side (only when zoomed). */
-export type DiffViewMode = "unified" | "split";
+/** How the Changes diff renders when wide: old|new side by side, or one stacked column. A narrow
+ *  (unzoomed) pane has no room for two columns, so it is always stacked regardless of this choice. */
+export type DiffViewMode = "split" | "stacked";
 
 /** One marker-popover quick action: a preset comment body, plus optional extra lines. */
 export interface QuickAction {
@@ -99,7 +100,7 @@ export interface CueloopConfig {
     editor?: string;
     /** The selected theme preset name; its tokens are the base for `theme`, before any `[theme]` overrides. */
     theme: ThemeName;
-    /** How the Changes diff renders when zoomed: one inline column or old|new side by side. */
+    /** How the Changes diff renders when wide: old|new side by side or one stacked column. */
     diffView: DiffViewMode;
     /** Session ids the user has pinned to the top of the sidebar; client-local view state. */
     pins: string[];
@@ -109,6 +110,13 @@ export interface CueloopConfig {
   /** Marker-popover quick actions ([[actions]] tables); the 5 defaults when unset. */
   actions: QuickAction[];
   integrations: IntegrationsConfig;
+  /** Opt-in experimental features ([experimental] table); all default off. */
+  experimental: ExperimentalConfig;
+}
+
+export interface ExperimentalConfig {
+  /** Render a prototype as a pixel mockup (kitty graphics) instead of the default markdown design doc. */
+  prototypePixels: boolean;
 }
 
 /** Every action in the grammar, with its default binding(s). */
@@ -143,6 +151,7 @@ const ConfigDocumentSchema = v.object({
   keys: v.optional(v.unknown()),
   theme: v.optional(v.unknown()),
   ui: v.optional(v.unknown()),
+  experimental: v.optional(v.unknown()),
 });
 
 const QuickActionSchema = v.object({
@@ -165,7 +174,7 @@ const UiSchema = v.object({
   ),
   editor: v.fallback(v.optional(v.string()), undefined),
   theme: v.fallback(v.optional(v.string()), undefined),
-  diff_view: v.fallback(v.optional(v.picklist(["unified", "split"])), undefined),
+  diff_view: v.fallback(v.optional(v.picklist(["split", "stacked", "unified"])), undefined),
   pins: v.fallback(v.optional(v.array(v.string())), undefined),
 });
 const ObsidianSchema = v.object({
@@ -176,6 +185,9 @@ const ObsidianSchema = v.object({
   exportOn: v.fallback(v.optional(v.picklist(["approve", "resolve", "manual"])), undefined),
 });
 const IntegrationsSchema = v.object({ obsidian: v.optional(ObsidianSchema) });
+const ExperimentalSchema = v.object({
+  prototype_pixels: v.fallback(v.optional(v.boolean()), undefined),
+});
 const ThemeOverridesSchema = v.record(v.string(), v.unknown());
 
 function isThemeToken(token: string): token is keyof Theme {
@@ -225,12 +237,14 @@ function layer(
     authors: { ...base.authors },
     actions: [...base.actions],
     integrations: { obsidian: { ...base.integrations.obsidian } },
+    experimental: { ...base.experimental },
   };
   const actions = parseActions(raw.actions);
   const authors = v.safeParse(AuthorsSchema, raw.authors);
   const keys = v.safeParse(KeysSchema, raw.keys);
   const ui = v.safeParse(UiSchema, raw.ui);
   const integrations = v.safeParse(IntegrationsSchema, raw.integrations);
+  const experimental = v.safeParse(ExperimentalSchema, raw.experimental);
 
   if (actions) out.actions = actions;
   if (authors.success) {
@@ -251,12 +265,17 @@ function layer(
   if (ui.success) {
     if (ui.output.auto_close !== undefined) out.ui.autoClose = ui.output.auto_close;
     if (ui.output.editor?.trim()) out.ui.editor = ui.output.editor.trim();
-    if (ui.output.diff_view !== undefined) out.ui.diffView = ui.output.diff_view;
+    // "unified" is the pre-rename spelling of "stacked"; keep loading it so an upgrade never flips the layout
+    if (ui.output.diff_view !== undefined)
+      out.ui.diffView = ui.output.diff_view === "unified" ? "stacked" : ui.output.diff_view;
     if (ui.output.pins !== undefined) out.ui.pins = ui.output.pins;
   }
   if (integrations.success && integrations.output.obsidian) {
     mergeObsidian(out.integrations.obsidian, integrations.output.obsidian);
   }
+  if (experimental.success && experimental.output.prototype_pixels !== undefined) {
+    out.experimental.prototypePixels = experimental.output.prototype_pixels;
+  }
 
   return out;
 }
@@ -271,12 +290,13 @@ export function loadConfig(
     ui: {
       autoClose: "off",
       theme: DEFAULT_THEME_NAME,
-      diffView: "unified",
+      diffView: "split",
       pins: [],
     },
     authors: {},
     actions: [...DEFAULT_QUICK_ACTIONS],
     integrations: { obsidian: { ...OBSIDIAN_DEFAULTS } },
+    experimental: { prototypePixels: false },
   };
   // Theme name and per-token overrides are separate concerns, composed once
   // after all layers: the last file to set [ui] theme wins, and every [theme]

package/src/ghostty-terminal.test.ts

@@ -21,10 +21,11 @@ describe("ghostty-terminal FFI", () => {
     term.write(new TextEncoder().encode("hi\x1b[1;32mGO\x1b[0m"));
     const cells = [0, 1, 2, 3].map((x) => term.readCell(x, 0));
 
-    // Assert - glyphs decode, and the green run is bold on ANSI palette index 2
+    // Assert - glyphs decode, the row reads as text, and the green run is bold on ANSI palette index 2
     expect(
       cells.map((c) => (c?.codepoint ? String.fromCodePoint(c.codepoint) : " ")).join(""),
     ).toBe("hiGO");
+    expect(term.rowText(0, 80)).toBe("hiGO");
     expect(cells[2]!.bold).toBe(true);
     expect(cells[2]!.fg).toEqual({ kind: "palette", index: 2 });
     term.free();

package/src/ghostty-terminal.ts

@@ -60,25 +60,31 @@ function nativeLibraryPath(): string | null {
   return existsSync(path) ? path : null;
 }
 
+/** One shared load of the VT library; null when no dylib ships or it failed to load. */
+let ghosttyFactory: GhosttyTerminalFactory | null | undefined;
+
 /**
  * Open the Ghostty VT library for this platform, or return null when the prebuilt
  * dylib is missing (the caller degrades to a herdr split instead of embedding).
+ * The library is opened once per process; later calls return the same factory.
  */
 export function loadGhosttyTerminals(): GhosttyTerminalFactory | null {
+  if (ghosttyFactory !== undefined) return ghosttyFactory;
   const path = nativeLibraryPath();
 
-  if (!path) return null;
+  if (!path) return (ghosttyFactory = null);
   try {
     const lib = dlopen(path, CVT_SYMBOLS);
 
-    return new GhosttyTerminalFactory(lib.symbols);
+    ghosttyFactory = new GhosttyTerminalFactory(lib.symbols);
   } catch (error) {
     // The file exists but failed to load (bad arch, missing symbol) - a real
     // fault, not the expected no-prebuilt case; surface it, then degrade.
     console.error(`cueloop: failed to load ${path}:`, error);
-
-    return null;
+    ghosttyFactory = null;
   }
+
+  return ghosttyFactory;
 }
 
 /** Creates `GhosttyTerminal`s that share one loaded copy of the VT library. */
@@ -146,6 +152,23 @@ export class GhosttyTerminal {
     };
   }
 
+  /**
+   * Row `y` as text: blank cells read as spaces, the trailing half of a wide
+   * glyph is skipped, and trailing spaces are trimmed.
+   */
+  rowText(y: number, cols: number): string {
+    let line = "";
+
+    for (let x = 0; x < cols; x++) {
+      const cell = this.readCell(x, y);
+
+      if (cell === null || cell.width === 2) continue;
+      line += cell.codepoint === 0 ? " " : String.fromCodePoint(cell.codepoint);
+    }
+
+    return line.trimEnd();
+  }
+
   /** The cursor's current viewport position and visibility. */
   readCursor(): GhosttyCursor {
     if (this.freed) return { x: 0, y: 0, visible: false };

package/src/intent-dispatch.test.ts

@@ -97,6 +97,8 @@ function baseController(): ReviewController {
     restoreCuration: mock(),
     edit: mock(),
     annotate: mock(() => undefined),
+    addComment: mock(() => undefined),
+    commentOnWorkbench: mock(() => Promise.resolve()),
     reply: mock(() => undefined),
     annotatePrototype: mock(() => undefined),
     updateAnnotation: mock(),

package/src/intent-dispatch.ts

@@ -113,7 +113,7 @@ export interface IntentDispatchDeps {
   selectCardFromDocument: (annotationId: string) => void;
   runEditorHandOff: () => void;
   openCardEdit: (annotationId: string) => void;
-  /** Flip unified/split diff and persist it (App-owned); split lays out only when zoomed. */
+  /** Flip split/stacked diff and persist it (App-owned); split lays out only when wide/zoomed. */
   toggleDiffView: () => void;
 }
 

package/src/key-bindings.test.ts

@@ -115,7 +115,7 @@ describe("getActiveKeys-generated status hints", () => {
 
   test("submit hint", () => {
     expect(bindings({ overlay: "submit" }).statusHint("submit")).toBe(
-      "verdict ←/→ · enter submit · esc cancel",
+      "decision ←/→ · enter submit · esc cancel",
     );
   });
 

package/src/key-bindings.ts

@@ -92,7 +92,11 @@ const HINT_TEMPLATES: Record<HintMode, HintEntry[]> = {
     { commands: ["cancel_overlay"], label: "cancel" },
   ],
   submit: [
-    { commands: ["cycle_verdict_left", "cycle_verdict_right"], label: "verdict", labelFirst: true },
+    {
+      commands: ["cycle_verdict_left", "cycle_verdict_right"],
+      label: "decision",
+      labelFirst: true,
+    },
     { commands: ["submit_verdict"], label: "submit" },
     { commands: ["cancel_submit"], label: "cancel" },
   ],

package/src/keymap.ts

@@ -372,7 +372,7 @@ function navigationIntent(action: string | undefined): Intent[] | null {
 }
 
 /** Ungated view toggles in the diff: right folds a file to its band, left unfolds it, s flips
- *  unified/split (split lays out only when the Changes pane is zoomed). */
+ *  split/stacked (split lays out only when the Changes pane is wide/zoomed). */
 function viewToggleIntent(action: string | undefined): Intent[] | null {
   if (action === "collapse_file") return [{ type: "foldFile" }];
   if (action === "expand_file") return [{ type: "unfoldFile" }];

package/src/prototype-browser.ts

@@ -42,6 +42,9 @@ export interface LaunchOptions {
   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. */
@@ -145,6 +148,11 @@ export async function launchPrototypeRenderer(options: LaunchOptions): Promise<P
       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" });

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/ready-signal.test.ts

@@ -0,0 +1,85 @@
+/** The ready signal fires once, after a frame, and writes the ready file when the env names one. */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createElement, useState } from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { READY_FILE_ENV, useReadySignal } from "./ready-signal";
+import { settle } from "./test-support";
+
+const homes: string[] = [];
+
+afterEach(() => {
+  for (const home of homes.splice(0)) rmSync(home, { recursive: true, force: true });
+  delete process.env[READY_FILE_ENV];
+});
+
+/** Hands its readiness setter to the test, so a frame can be rendered before and after the flip. */
+function ReadyProbe(props: {
+  initiallyReady: boolean;
+  onReady: () => void;
+  exposeSetter?: (setReady: (ready: boolean) => void) => void;
+}) {
+  const [ready, setReady] = useState(props.initiallyReady);
+
+  props.exposeSetter?.(setReady);
+  useReadySignal(ready, props.onReady);
+
+  return createElement("text", null, ready ? "ready" : "booting");
+}
+
+describe("useReadySignal", () => {
+  test("fires once on the first frame after ready turns true", async () => {
+    // Arrange - not ready yet
+    let fired = 0;
+    let setReady: ((ready: boolean) => void) | null = null;
+    const onReady = () => {
+      fired += 1;
+    };
+    const setup = await testRender(
+      createElement(ReadyProbe, {
+        initiallyReady: false,
+        onReady,
+        exposeSetter: (setter) => {
+          setReady = setter;
+        },
+      }),
+      { width: 20, height: 3 },
+    );
+
+    await settle(setup);
+    expect(fired).toBe(0);
+
+    // Act - ready, then let the commit, the effect, and more frames than one signal needs run
+    setReady!(true);
+    await settle(setup);
+    await settle(setup);
+
+    // Assert - exactly one signal, and the screen shows the ready tree
+    expect(fired).toBe(1);
+    expect(setup.captureCharFrame()).toContain("ready");
+    setup.renderer.destroy();
+  });
+
+  test("writes the ready file through the env channel", async () => {
+    // Arrange
+    const home = mkdtempSync(join(tmpdir(), "cueloop-ready-"));
+    const readyFile = join(home, "ready");
+
+    homes.push(home);
+    process.env[READY_FILE_ENV] = readyFile;
+    const setup = await testRender(
+      createElement(ReadyProbe, { initiallyReady: true, onReady: () => {} }),
+      { width: 20, height: 3 },
+    );
+
+    // Act
+    await settle(setup);
+
+    // Assert
+    expect(existsSync(readyFile)).toBe(true);
+    setup.renderer.destroy();
+  });
+});

package/src/ready-signal.ts

@@ -0,0 +1,52 @@
+/**
+ * The app ready signal: fired once, after the first frame that paints a
+ * usable screen (a session, the no-thread shell, or an error) has been
+ * flushed. React runs child effects before parent effects, so by the time the
+ * App-level effect arms the frame listener every keyboard handler of that
+ * first screen is already subscribed - a key sent after the signal cannot be
+ * dropped. Surfaces that mount later (a composer, a lazily loaded tab) still
+ * need their own screen predicate. Tests wait on this instead of guessing
+ * from output silence. Two channels: an
+ * `onReady` callback for in-process suites, and the file named by
+ * CUELOOP_READY_FILE for subprocess and PTY suites. Users never see either.
+ */
+
+import { writeFileSync } from "node:fs";
+import { useEffect, useRef } from "react";
+import { useRenderer } from "@opentui/react";
+
+/** The env var naming the file the app writes once it is ready; unset in normal use. */
+export const READY_FILE_ENV = "CUELOOP_READY_FILE";
+
+/** Write the ready file when CUELOOP_READY_FILE names one; a no-op otherwise, so the signal costs nothing outside tests. */
+function announceReady(): void {
+  const path = process.env[READY_FILE_ENV];
+
+  if (!path) return;
+  writeFileSync(path, "ready\n");
+}
+
+/**
+ * Fire the ready signal once, on the first rendered frame after `ready`
+ * turns true. Call it after every keyboard hook of the component so their
+ * subscriptions are in place when the signal goes out.
+ */
+export function useReadySignal(ready: boolean, onReady?: () => void): void {
+  const renderer = useRenderer();
+  const fired = useRef(false);
+
+  useEffect(() => {
+    if (!ready || fired.current) return;
+    const emit = (): void => {
+      fired.current = true;
+      announceReady();
+      onReady?.();
+    };
+
+    renderer?.once("frame", emit);
+
+    return () => {
+      renderer?.off("frame", emit);
+    };
+  }, [ready, renderer, onReady]);
+}