@cueloop/client 0.1.0-alpha.46 → 0.1.0-alpha.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.46",
+  "version": "0.1.0-alpha.48",
   "description": "The cueloop review UI: projection renderer, keyboard grammar, review rail",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -26,10 +26,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/daemon": "0.1.0-alpha.46",
-    "@cueloop/extension-api": "0.1.0-alpha.46",
-    "@cueloop/integration-obsidian": "0.1.0-alpha.46",
-    "@cueloop/schema": "0.1.0-alpha.46",
+    "@cueloop/daemon": "0.1.0-alpha.48",
+    "@cueloop/extension-api": "0.1.0-alpha.48",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.48",
+    "@cueloop/schema": "0.1.0-alpha.48",
     "@opentui/core": "^0.5.2",
     "@opentui/keymap": "0.5.2",
     "@opentui/react": "^0.5.2",

package/src/App.prototype.test.tsx

@@ -0,0 +1,155 @@
+/** Prototype review end to end: a click on the rendered page selects a DOM element, the marker actions bar opens, a typed comment saves through the controller, and the annotation shows in the rail. The headless browser is replaced with a fake so no Chrome or kitty output is needed. Char-frame assertions over the real App and a real in-process daemon. */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import React from "react";
+import { testRender } from "@opentui/react/test-utils";
+import { DaemonServer } from "@cueloop/daemon";
+import type { ReviewSession } from "@cueloop/schema";
+import { App } from "./App";
+import {
+  setPrototypeRendererFactory,
+  type PrototypeElement,
+  type PrototypeRenderer,
+} from "./prototype-browser";
+import {
+  isolateUserConfig,
+  press,
+  settle,
+  typeText,
+  waitForState,
+  waitForText,
+  waitForTextGone,
+} from "./test-support";
+
+const HTML = "<main><div class='card'><h2>Pro</h2><p>$24/mo</p></div></main>";
+
+const FAKE_ELEMENT: PrototypeElement = {
+  selector: "main > div.card",
+  quote: "Pro $24/mo",
+  // mid-page, so the popover anchors well away from the click point below
+  box: { x: 440, y: 320, width: 320, height: 220 },
+};
+
+let rendered = false;
+let scrollDeltas: number[] = [];
+const fakeRenderer: PrototypeRenderer = {
+  viewport: { width: 1280, height: 800 },
+  screenshot: async () => {
+    rendered = true;
+    return new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+  },
+  elementAt: async () => FAKE_ELEMENT,
+  highlight: async () => undefined,
+  scrollBy: async (deltaY) => {
+    scrollDeltas.push(deltaY);
+    return true;
+  },
+  close: async () => undefined,
+};
+
+let home: string;
+let server: DaemonServer;
+let session: ReviewSession;
+let restoreUserConfig: () => void;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "cueloop-prototype-"));
+  restoreUserConfig = isolateUserConfig(home);
+  server = new DaemonServer({ home, idleExitMs: 0 });
+  server.start();
+  session = server.core.sessionCreate({
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: {
+      type: "prototype",
+      content: HTML,
+      meta: { title: "Pricing cards", prototypePath: "/repo/cards.html" },
+    },
+  });
+  rendered = false;
+  scrollDeltas = [];
+  setPrototypeRendererFactory(async () => fakeRenderer);
+});
+afterEach(() => {
+  setPrototypeRendererFactory(null);
+  restoreUserConfig();
+  server.stop();
+  rmSync(home, { recursive: true, force: true });
+});
+
+async function renderApp() {
+  const setup = await testRender(<App home={home} sessionId={session.id} />, {
+    width: 120,
+    height: 32,
+  });
+  await waitForText(setup, "cueloop");
+  return setup;
+}
+
+type Setup = Awaited<ReturnType<typeof renderApp>>;
+
+async function clickText(setup: Setup, needle: string): Promise<void> {
+  const lines = setup.captureCharFrame().split("\n");
+  const row = lines.findIndex((line) => line.includes(needle));
+  await setup.mockMouse.click(lines[row]!.indexOf(needle) + 1, row);
+  await setup.renderOnce();
+}
+
+describe("prototype review", () => {
+  test("click an element, comment on it, and it lands in the rail", async () => {
+    // Arrange - wait until the fake browser produced its first screenshot, so
+    // the sheet is interactive before the click
+    const setup = await renderApp();
+    await waitForState(setup, () => rendered);
+    await settle(setup);
+
+    // Act
+    await setup.mockMouse.click(6, 6);
+    await waitForText(setup, "comment");
+    await clickText(setup, "comment");
+    await waitForText(setup, "write a note");
+    // the keymap-suppression flag must propagate before typing so keys reach the
+    // textarea, not the global keymap
+    await settle(setup);
+    await typeText(setup, "tighten the padding");
+    await press(setup, "enter");
+
+    // Assert - the annotation is stored against the element's selector
+    await waitForState(setup, () => server.core.sessionGet(session.id).annotations.length === 1);
+    const stored = server.core.sessionGet(session.id).annotations[0]!;
+    expect(stored.kind).toBe("comment");
+    expect(stored.body).toBe("tighten the padding");
+    expect(stored.anchor.selector).toBe("main > div.card");
+
+    // and it renders in the rail
+    await settle(setup);
+    const frame = setup.captureCharFrame();
+    expect(frame).toContain("tighten the padding");
+    expect(frame).toContain("COMMENT");
+  });
+
+  test("wheel over the preview scrolls the page down, then up, and clears a selection", async () => {
+    // Arrange
+    const setup = await renderApp();
+    await waitForState(setup, () => rendered);
+    await settle(setup);
+
+    // open a selection, then scroll: the scroll drops it (it would drift once
+    // the page moves under it)
+    await setup.mockMouse.click(6, 6);
+    await waitForText(setup, "comment");
+    await setup.mockMouse.scroll(6, 6, "down");
+    await waitForState(setup, () => scrollDeltas.length === 1);
+    await waitForTextGone(setup, "comment");
+
+    // Act - scroll back up
+    await setup.mockMouse.scroll(6, 6, "up");
+    await waitForState(setup, () => scrollDeltas.length === 2);
+
+    // Assert - down was a positive delta, up was negative
+    expect(scrollDeltas[0]!).toBeGreaterThan(0);
+    expect(scrollDeltas[1]!).toBeLessThan(0);
+  });
+});

package/src/App.tsx

@@ -253,6 +253,7 @@ export function App({
   const resolved = session?.status === "resolved";
   const isDiff = session?.artifact.type === "diff";
   const isPrototype = session?.artifact.type === "prototype";
+  const [prototypeComposing, setPrototypeComposing] = useState(false);
   // sort position per annotation so the rail interleaves annotation and removal
   // cards in one line-ordered stack: a diff row carries its blockIndex; a plan
   // annotation resolves to the display index it marked
@@ -589,6 +590,9 @@ export function App({
   };
 
   useKeyboard((key) => {
+    // The prototype compose textarea owns the keyboard while open: let it receive
+    // the typed note instead of the global keymap acting on each letter.
+    if (prototypeComposing) return;
     // A running in-tab agent terminal owns the keyboard: forward every key to it,
     // with ctrl+] as the detach chord back to the review.
     if (agentTerminal) {
@@ -1035,6 +1039,8 @@ export function App({
               onCommentElement={(element, body) =>
                 controller.annotatePrototype(element.selector, element.quote, body)
               }
+              onComposingChange={setPrototypeComposing}
+              hidden={menuOpen || menuDialog !== null}
             />
           ) : isDiff ? (
             // the sheet dims to reading-quiet colors while the wizard has focus

package/src/components/AnnotationCard.tsx

@@ -25,6 +25,12 @@ export interface AnnotationDraft {
   onInput: (text: string) => void;
   onSave: () => void;
   onCancel: () => void;
+  /**
+   * When set, ⏎ in the textarea saves through this handler. The plan and diff
+   * composers leave it unset because the app keymap owns ⏎ there; the prototype
+   * composer sets it because the app keymap is suppressed while it is open.
+   */
+  onSubmit?: () => void;
 }
 
 export interface AnnotationSaved {
@@ -119,6 +125,7 @@ function DraftEditor({
         initialValue={draft.text}
         placeholder="write a note..."
         keyBindings={COMPOSE_KEY_BINDINGS}
+        {...(draft.onSubmit ? { onSubmit: draft.onSubmit } : {})}
         onContentChange={() => {
           const editor = editorRef.current;
           if (!editor) return;

package/src/components/PrototypeSheet.tsx

@@ -1,11 +1,15 @@
 /**
- * Prototype review surface: renders the HTML as an image and turns a click into
- * a DOM-element selection, so the shared marker actions bar and compose card
- * annotate an element rather than a text span.
+ * Prototype review surface: renders the HTML screenshot into a reserved cell
+ * region via the kitty graphics protocol, and turns a click into a DOM-element
+ * selection, so the shared marker actions bar and compose card annotate an
+ * element rather than a text span. The image is painted directly (not through
+ * OpenTUI's ImageRenderable, which does not display in every terminal): the
+ * region's cells are never repainted, and the picture is re-placed after each
+ * frame so it survives OpenTUI's own draws.
  */
 
 import React, { useEffect, useRef, useState } from "react";
-import type { ImageRenderable } from "@opentui/core";
+import type { BoxRenderable } from "@opentui/core";
 import { useRenderer } from "@opentui/react";
 import type { Theme } from "../theme";
 import { quickActionBody, type QuickAction } from "../config";
@@ -16,79 +20,181 @@ import { AnnotationCard } from "./AnnotationCard";
 import {
   cssBoxToCell,
   imageCellToCss,
-  launchPrototypeRenderer,
+  prototypeRendererFactory,
   type PrototypeElement,
   type PrototypeRenderer,
   type PrototypeViewport,
 } from "../prototype-browser";
+import {
+  deleteKittyImage,
+  placeKittyImage,
+  transmitKittyImage,
+  type CellRegion,
+} from "../kitty-image";
 
 export interface PrototypeSheetProps {
   prototypePath: string;
   quickActions: QuickAction[];
   canComment: boolean;
   onCommentElement: (element: PrototypeElement, body: string) => void;
+  /** Signals when the inline compose owns the keyboard, so the app suppresses
+   *  its global keymap and the compose textarea receives the typed note. */
+  onComposingChange?: (active: boolean) => void;
+  /** True while an app overlay (menu, settings) covers the sheet; the image is
+   *  removed so those overlays are not shown through the graphics layer. */
+  hidden?: boolean;
   theme?: Theme;
 }
 
 type SheetStatus = "loading" | "ready" | "unsupported" | "error";
 
-const DEFAULT_CELL_ASPECT = 2;
 const POPOVER_ROWS = 3;
+const PROTOTYPE_IMAGE_ID = 811;
+/** Page pixels scrolled per wheel notch. */
+const SCROLL_STEP = 240;
+// The capture viewport width in CSS pixels; its height matches the region's
+// cell aspect so the rendered image fills the box instead of letterboxing. The
+// aspect comes from the terminal's reported cell pixels, falling back to a
+// typical monospace ratio when the terminal never reports one.
+const CAPTURE_WIDTH = 1280;
+const FALLBACK_CELL_HEIGHT_OVER_WIDTH = 2.18;
+
+function cellHeightOverWidth(renderer: {
+  resolution: { width: number; height: number } | null;
+  terminalWidth: number;
+  terminalHeight: number;
+}): number {
+  const resolution = renderer.resolution;
+  if (!resolution || renderer.terminalWidth < 1 || renderer.terminalHeight < 1) {
+    return FALLBACK_CELL_HEIGHT_OVER_WIDTH;
+  }
+  return resolution.height / renderer.terminalHeight / (resolution.width / renderer.terminalWidth);
+}
+
+function regionOf(box: BoxRenderable | null): CellRegion | null {
+  if (!box || box.width < 1 || box.height < 1) return null;
+  return { column: box.x, row: box.y, columns: box.width, rows: box.height };
+}
 
 export function PrototypeSheet({
   prototypePath,
   quickActions,
   canComment,
   onCommentElement,
+  onComposingChange,
+  hidden = false,
   theme,
 }: PrototypeSheetProps): React.ReactNode {
   const tokens = useComponentTheme(theme);
   const renderer = useRenderer();
-  const imageRef = useRef<ImageRenderable | null>(null);
+  const regionRef = useRef<BoxRenderable | null>(null);
   const browserRef = useRef<PrototypeRenderer | null>(null);
   const launchedRef = useRef(false);
-  const viewportRef = useRef<PrototypeViewport>({ width: 1280, height: 800 });
+  const viewportRef = useRef<PrototypeViewport>({ width: CAPTURE_WIDTH, height: 800 });
+  const pngRef = useRef<Uint8Array | null>(null);
+  const transmittedRef = useRef<Uint8Array | null>(null);
+  const paintRef = useRef<() => void>(() => undefined);
+  const launchRef = useRef<() => void>(() => undefined);
+  const hiddenRef = useRef(hidden);
+  useEffect(() => {
+    hiddenRef.current = hidden;
+  });
 
   const [status, setStatus] = useState<SheetStatus>("loading");
   const [errorMessage, setErrorMessage] = useState<string>("");
-  const [png, setPng] = useState<Uint8Array | null>(null);
   const [selected, setSelected] = useState<PrototypeElement | null>(null);
   const [overlayCell, setOverlayCell] = useState<{ left: number; top: number } | null>(null);
   const [actionsOpen, setActionsOpen] = useState(false);
   const [composing, setComposing] = useState(false);
   const [draftText, setDraftText] = useState("");
 
+  const setPng = (png: Uint8Array): void => {
+    pngRef.current = png;
+    transmittedRef.current = null;
+    paintRef.current();
+  };
+
+  // Every frame: start the browser once layout is known, then keep the picture
+  // asserted over its cells. The kitty emission (transmit once, cheap re-place
+  // after) is skipped when the renderer has no raw writeOut channel (the test
+  // harness), but the launch trigger still runs.
   useEffect(() => {
+    if (!renderer) return;
+    // writeOut is the renderer's raw output channel, ordered against its frame
+    // bytes; it is private, so reach it through one narrow cast
+    const rawWrite = (renderer as unknown as { writeOut?: (data: string) => void }).writeOut;
+    const write =
+      typeof rawWrite === "function" ? (chunk: string) => rawWrite.call(renderer, chunk) : null;
+    const paint = (): void => {
+      if (!write) return;
+      // an app overlay is covering the sheet: pull the image so it does not show
+      // through the overlay's cells, and re-transmit once the overlay closes
+      if (hiddenRef.current) {
+        if (transmittedRef.current !== null) {
+          deleteKittyImage(write, PROTOTYPE_IMAGE_ID);
+          transmittedRef.current = null;
+        }
+        return;
+      }
+      const region = regionOf(regionRef.current);
+      const png = pngRef.current;
+      if (!region || !png) return;
+      if (transmittedRef.current !== png) {
+        transmitKittyImage(write, png, region, PROTOTYPE_IMAGE_ID);
+        transmittedRef.current = png;
+      } else {
+        placeKittyImage(write, region, PROTOTYPE_IMAGE_ID);
+      }
+    };
+    paintRef.current = paint;
+    const onFrame = (): void => {
+      launchRef.current();
+      paint();
+    };
+    renderer.on("frame", onFrame);
     return () => {
-      void browserRef.current?.close();
+      renderer.off("frame", onFrame);
+      if (write) deleteKittyImage(write, PROTOTYPE_IMAGE_ID);
     };
-  }, []);
+  }, [renderer]);
+
+  useEffect(() => {
+    onComposingChange?.(composing);
+  }, [composing, onComposingChange]);
 
-  const viewportFor = (columns: number, rows: number): PrototypeViewport => {
-    const resolution = renderer?.resolution ?? null;
-    const cellWidth = resolution ? resolution.width / renderer!.terminalWidth : 1;
-    const cellHeight = resolution
-      ? resolution.height / renderer!.terminalHeight
-      : DEFAULT_CELL_ASPECT;
-    return {
-      width: Math.max(320, Math.round(columns * cellWidth)),
-      height: Math.max(240, Math.round(rows * cellHeight)),
+  const unmountedRef = useRef(false);
+  useEffect(() => {
+    return () => {
+      unmountedRef.current = true;
+      void browserRef.current?.close();
     };
-  };
+  }, []);
 
   const launch = (): void => {
-    const image = imageRef.current;
-    if (launchedRef.current || !image || image.width < 1 || image.height < 1) return;
-    if (renderer?.capabilities && renderer.capabilities.kitty_graphics === false) {
+    const region = regionOf(regionRef.current);
+    const caps = renderer?.capabilities;
+    if (launchedRef.current || !region) return;
+    if (caps && caps.kitty_graphics === false) {
       setStatus("unsupported");
       return;
     }
     launchedRef.current = true;
-    const viewport = viewportFor(image.width, image.height);
+    const viewport = {
+      width: CAPTURE_WIDTH,
+      height: Math.round(
+        (CAPTURE_WIDTH * region.rows * cellHeightOverWidth(renderer!)) / region.columns,
+      ),
+    };
     viewportRef.current = viewport;
     void (async () => {
       try {
-        const browser = await launchPrototypeRenderer({ filePath: prototypePath, viewport });
+        const browser = await prototypeRendererFactory()({ filePath: prototypePath, viewport });
+        // the sheet may have unmounted while Chromium was launching; close the
+        // late arrival instead of leaking the process
+        if (unmountedRef.current) {
+          void browser.close();
+          return;
+        }
         browserRef.current = browser;
         setPng(await browser.screenshot());
         setStatus("ready");
@@ -98,6 +204,9 @@ export function PrototypeSheet({
       }
     })();
   };
+  useEffect(() => {
+    launchRef.current = launch;
+  });
 
   const refresh = async (): Promise<void> => {
     const browser = browserRef.current;
@@ -116,11 +225,16 @@ export function PrototypeSheet({
       .catch(() => undefined);
   };
 
-  const onImageMouseDown = (event: { x: number; y: number }): void => {
+  const onRegionMouseDown = (event: { x: number; y: number }): void => {
     const browser = browserRef.current;
-    const image = imageRef.current;
-    if (status !== "ready" || !browser || !image) return;
-    const geometry = { x: image.x, y: image.y, width: image.width, height: image.height };
+    const region = regionOf(regionRef.current);
+    if (status !== "ready" || !browser || !region) return;
+    const geometry = {
+      x: region.column,
+      y: region.row,
+      width: region.columns,
+      height: region.rows,
+    };
     const cssPoint = imageCellToCss(event, geometry, viewportRef.current);
     if (!cssPoint) return;
     void (async () => {
@@ -143,19 +257,32 @@ export function PrototypeSheet({
     });
   };
 
+  const onRegionScroll = (event: { scroll?: { direction: string } }): void => {
+    const browser = browserRef.current;
+    if (status !== "ready" || !browser) return;
+    const delta = event.scroll?.direction === "up" ? -SCROLL_STEP : SCROLL_STEP;
+    // a selection would drift once the page scrolls under it, so drop it
+    clearSelection();
+    void browser
+      .scrollBy(delta)
+      .then(() => refresh())
+      .catch(() => undefined);
+  };
+
   const commit = (body: string): void => {
     if (!canComment) return;
     if (selected && body.trim()) onCommentElement(selected, body.trim());
     clearSelection();
   };
 
-  const overlayLeft = overlayCell?.left ?? 0;
-  const overlayTop = Math.max(0, overlayCell?.top ?? 0);
+  // the overlay carries an opaque fill so the popover and compose card read as
+  // solid cards over the image, matching the plan surface
   const overlayStyle = {
     position: "absolute" as const,
-    left: overlayLeft,
-    top: overlayTop,
+    left: overlayCell?.left ?? 0,
+    top: Math.max(0, overlayCell?.top ?? 0),
     flexDirection: "column" as const,
+    backgroundColor: tokens.elevated,
   };
 
   return (
@@ -168,16 +295,14 @@ export function PrototypeSheet({
         borderColor: tokens.text,
       }}
     >
-      <image
-        ref={(instance: ImageRenderable | null) => {
-          imageRef.current = instance;
+      <box
+        ref={(instance: BoxRenderable | null) => {
+          regionRef.current = instance;
         }}
-        {...(png ? { source: png } : {})}
-        fit="fill"
-        protocol="auto"
         style={{ flexGrow: 1 }}
         onSizeChange={launch}
-        onMouseDown={onImageMouseDown}
+        onMouseDown={onRegionMouseDown}
+        onMouseScroll={onRegionScroll}
       />
       {status !== "ready" ? (
         <box style={{ position: "absolute", left: 2, top: 1 }}>
@@ -191,7 +316,11 @@ export function PrototypeSheet({
             actions={quickActions}
             actionIndex={0}
             canCut={false}
-            onComment={() => (canComment ? setComposing(true) : undefined)}
+            onComment={() => {
+              if (!canComment) return;
+              onComposingChange?.(true);
+              setComposing(true);
+            }}
             onCut={() => undefined}
             onOpenActions={() => setActionsOpen(true)}
             onClose={clearSelection}
@@ -210,6 +339,7 @@ export function PrototypeSheet({
               text: draftText,
               onInput: setDraftText,
               onSave: () => commit(draftText),
+              onSubmit: () => commit(draftText),
               onCancel: clearSelection,
             }}
             theme={theme}

package/src/components/__snapshots__/stories.test.tsx.snap

@@ -817,6 +817,34 @@ exports[`stories catalog PromptDialog/RenameAuthor renders, snapshots, and carri
                                                                 
                                                                 
                                                                 
+"
+`;
+
+exports[`stories catalog PrototypeSheet/Unsupported renders, snapshots, and carries its colors: PrototypeSheet/Unsupported 1`] = `
+"╭──────────────────────────────────────────────────────────────────────────────╮
+│                                                                              │
+│  rendering prototype…                                                        │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+╰──────────────────────────────────────────────────────────────────────────────╯
 "
 `;
 
@@ -1825,33 +1853,5 @@ exports[`stories catalog theme-context/ProviderSwap renders, snapshots, and carr
                                                                                 
                                                                                 
                                                                                 
-"
-`;
-
-exports[`stories catalog PrototypeSheet/Unsupported renders, snapshots, and carries its colors: PrototypeSheet/Unsupported 1`] = `
-"╭──────────────────────────────────────────────────────────────────────────────╮
-│                                                                              │
-│  rendering prototype…                                                        │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-│                                                                              │
-╰──────────────────────────────────────────────────────────────────────────────╯
 "
 `;

package/src/kitty-image.ts

@@ -0,0 +1,74 @@
+/**
+ * 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, then re-place it after each
+ * frame over its reserved (never-repainted) cells, cell-addressed so it needs no
+ * pixel-resolution report.
+ */
+
+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;
+
+const ESCAPE_STRING_TERMINATOR = "\x1b\\";
+const CHUNK_BYTES = 4096;
+
+/** 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}`;
+}
+
+/**
+ * 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. Data over 4096 bytes is chunked.
+ */
+export function transmitKittyImage(
+  write: OrderedWrite,
+  png: Uint8Array,
+  region: CellRegion,
+  imageId: number,
+): void {
+  if (region.columns < 1 || region.rows < 1) return;
+  const base64 = Buffer.from(png).toString("base64");
+  // z<0 places the image beneath the text layer, so the marker popover and
+  // compose card (ordinary cells) still paint over it
+  const controlKeys = `a=T,f=100,i=${imageId},q=2,C=1,z=-1,c=${region.columns},r=${region.rows}`;
+  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);
+  }
+  write(atRegion(region, sequence));
+}
+
+/** Re-place an 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;
+  const command = graphicsCommand(
+    `a=p,i=${imageId},q=2,C=1,z=-1,c=${region.columns},r=${region.rows}`,
+    "",
+  );
+  write(atRegion(region, command));
+}
+
+/** 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/prototype-browser.ts

@@ -31,6 +31,8 @@ export interface PrototypeRenderer {
   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>;
 }
 
@@ -79,6 +81,20 @@ export function cssBoxToCell(
   };
 }
 
+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");
@@ -116,6 +132,9 @@ export async function launchPrototypeRenderer(options: LaunchOptions): Promise<P
     async highlight(selector) {
       await page.evaluate(highlightScript, selector);
     },
+    async scrollBy(deltaY) {
+      return (await page.evaluate(scrollByScript, deltaY)) as boolean;
+    },
     async close() {
       await browser.close();
     },
@@ -187,6 +206,12 @@ function elementAtScript(x: number, y: number): unknown {
   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";