@cueloop/client 0.1.0-alpha.45 → 0.1.0-alpha.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.45",
+  "version": "0.1.0-alpha.47",
   "description": "The cueloop review UI: projection renderer, keyboard grammar, review rail",
   "homepage": "https://github.com/mmurakaru/cueloop#readme",
   "bugs": {
@@ -26,16 +26,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@cueloop/daemon": "0.1.0-alpha.45",
-    "@cueloop/extension-api": "0.1.0-alpha.45",
-    "@cueloop/integration-obsidian": "0.1.0-alpha.45",
-    "@cueloop/schema": "0.1.0-alpha.45",
+    "@cueloop/daemon": "0.1.0-alpha.47",
+    "@cueloop/extension-api": "0.1.0-alpha.47",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.47",
+    "@cueloop/schema": "0.1.0-alpha.47",
     "@opentui/core": "^0.5.2",
     "@opentui/keymap": "0.5.2",
     "@opentui/react": "^0.5.2",
     "@opentui/ssh": "0.5.2",
     "@pierre/diffs": "^1.3.5",
     "diff": "^8",
+    "puppeteer-core": "^25.8.0",
     "react": "^19.2.0"
   },
   "devDependencies": {

package/src/App.prototype.test.tsx

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

package/src/App.tsx

@@ -58,6 +58,7 @@ import { CLIENT_VERSION } from "./version";
 import { Breadcrumb, type BreadcrumbItem } from "./components/Breadcrumb";
 import { PlanSheet, type PlanSheetHandle } from "./components/PlanSheet";
 import { DiffSheet } from "./components/DiffSheet";
+import { PrototypeSheet } from "./components/PrototypeSheet";
 import { type ReviewRailHandle } from "./components/ReviewRail";
 import type { AgentTerminalHandle } from "./components/agent-launcher";
 import { ReviewPanel } from "./components/ReviewPanel";
@@ -251,6 +252,8 @@ export function App({
   }, [marks]);
   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
@@ -587,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) {
@@ -1025,7 +1031,17 @@ export function App({
           <box style={{ width: railFootprint }} />
         </box>
         <box style={{ flexGrow: 1, flexDirection: "row" }}>
-          {isDiff ? (
+          {isPrototype ? (
+            <PrototypeSheet
+              prototypePath={activeSession.artifact.meta.prototypePath ?? ""}
+              quickActions={quickActions}
+              canComment={isOwner && !resolved}
+              onCommentElement={(element, body) =>
+                controller.annotatePrototype(element.selector, element.quote, body)
+              }
+              onComposingChange={setPrototypeComposing}
+            />
+          ) : isDiff ? (
             // the sheet dims to reading-quiet colors while the wizard has focus
             <DiffSheet
               rows={rows}
@@ -1061,7 +1077,7 @@ export function App({
               session: activeSession,
               authorNames,
               selectedId: focusedAnnotationId,
-              resolvedIds: isDiff ? null : resolvedIds,
+              resolvedIds: isDiff || isPrototype ? null : resolvedIds,
               curationItems,
               selectedCurationId,
               annotationPositions,

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.stories.tsx

@@ -0,0 +1,20 @@
+import React from "react";
+import { DARK } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { PrototypeSheet } from "./PrototypeSheet";
+
+export const meta: StoryMeta = { title: "PrototypeSheet" };
+
+// The story renderer reports no kitty graphics, so the sheet shows its fallback.
+export const Unsupported: Story = {
+  render: () => (
+    <PrototypeSheet
+      prototypePath="/tmp/example.html"
+      quickActions={[]}
+      canComment={true}
+      onCommentElement={() => {}}
+    />
+  ),
+  expectedColors: [DARK.textDim],
+  size: { width: 80, height: 24 },
+};

package/src/components/PrototypeSheet.tsx

@@ -0,0 +1,323 @@
+/**
+ * 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 { BoxRenderable } from "@opentui/core";
+import { useRenderer } from "@opentui/react";
+import type { Theme } from "../theme";
+import { quickActionBody, type QuickAction } from "../config";
+import { useComponentTheme } from "./theme-context";
+import { FRAME_BORDER_STYLE } from "./primitives/frame";
+import { MarkerPopover } from "./MarkerPopover";
+import { AnnotationCard } from "./AnnotationCard";
+import {
+  cssBoxToCell,
+  imageCellToCss,
+  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;
+  theme?: Theme;
+}
+
+type SheetStatus = "loading" | "ready" | "unsupported" | "error";
+
+const POPOVER_ROWS = 3;
+const PROTOTYPE_IMAGE_ID = 811;
+// 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,
+  theme,
+}: PrototypeSheetProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const renderer = useRenderer();
+  const regionRef = useRef<BoxRenderable | null>(null);
+  const browserRef = useRef<PrototypeRenderer | null>(null);
+  const launchedRef = useRef(false);
+  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 [status, setStatus] = useState<SheetStatus>("loading");
+  const [errorMessage, setErrorMessage] = useState<string>("");
+  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;
+      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 () => {
+      renderer.off("frame", onFrame);
+      if (write) deleteKittyImage(write, PROTOTYPE_IMAGE_ID);
+    };
+  }, [renderer]);
+
+  useEffect(() => {
+    onComposingChange?.(composing);
+  }, [composing, onComposingChange]);
+
+  const unmountedRef = useRef(false);
+  useEffect(() => {
+    return () => {
+      unmountedRef.current = true;
+      void browserRef.current?.close();
+    };
+  }, []);
+
+  const launch = (): void => {
+    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 = {
+      width: CAPTURE_WIDTH,
+      height: Math.round(
+        (CAPTURE_WIDTH * region.rows * cellHeightOverWidth(renderer!)) / region.columns,
+      ),
+    };
+    viewportRef.current = viewport;
+    void (async () => {
+      try {
+        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");
+      } catch (error) {
+        setErrorMessage(error instanceof Error ? error.message : String(error));
+        setStatus("error");
+      }
+    })();
+  };
+  useEffect(() => {
+    launchRef.current = launch;
+  });
+
+  const refresh = async (): Promise<void> => {
+    const browser = browserRef.current;
+    if (browser) setPng(await browser.screenshot());
+  };
+
+  const clearSelection = (): void => {
+    setSelected(null);
+    setOverlayCell(null);
+    setActionsOpen(false);
+    setComposing(false);
+    setDraftText("");
+    void browserRef.current
+      ?.highlight(null)
+      .then(refresh)
+      .catch(() => undefined);
+  };
+
+  const onRegionMouseDown = (event: { x: number; y: number }): void => {
+    const browser = browserRef.current;
+    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 () => {
+      const element = await browser.elementAt(cssPoint.x, cssPoint.y);
+      if (!element) return;
+      const cell = cssBoxToCell(element.box, geometry, viewportRef.current);
+      const topRaw = cell.row - geometry.y;
+      setSelected(element);
+      setOverlayCell({
+        left: Math.max(0, cell.column - geometry.x),
+        top: Math.max(0, topRaw < POPOVER_ROWS ? topRaw + 1 : topRaw - POPOVER_ROWS),
+      });
+      setActionsOpen(false);
+      setComposing(false);
+      await browser.highlight(element.selector);
+      await refresh();
+    })().catch((error) => {
+      setErrorMessage(error instanceof Error ? error.message : String(error));
+      setStatus("error");
+    });
+  };
+
+  const commit = (body: string): void => {
+    if (!canComment) return;
+    if (selected && body.trim()) onCommentElement(selected, body.trim());
+    clearSelection();
+  };
+
+  const overlayStyle = {
+    position: "absolute" as const,
+    left: overlayCell?.left ?? 0,
+    top: Math.max(0, overlayCell?.top ?? 0),
+    flexDirection: "column" as const,
+  };
+
+  return (
+    <box
+      style={{
+        flexGrow: 1,
+        flexDirection: "column",
+        border: true,
+        borderStyle: FRAME_BORDER_STYLE,
+        borderColor: tokens.text,
+      }}
+    >
+      <box
+        ref={(instance: BoxRenderable | null) => {
+          regionRef.current = instance;
+        }}
+        style={{ flexGrow: 1 }}
+        onSizeChange={launch}
+        onMouseDown={onRegionMouseDown}
+      />
+      {status !== "ready" ? (
+        <box style={{ position: "absolute", left: 2, top: 1 }}>
+          <text fg={tokens.textDim}>{statusLine(status, errorMessage)}</text>
+        </box>
+      ) : null}
+      {selected && !composing ? (
+        <box style={overlayStyle}>
+          <MarkerPopover
+            view={actionsOpen ? "actions" : "toolbar"}
+            actions={quickActions}
+            actionIndex={0}
+            canCut={false}
+            onComment={() => {
+              if (!canComment) return;
+              onComposingChange?.(true);
+              setComposing(true);
+            }}
+            onCut={() => undefined}
+            onOpenActions={() => setActionsOpen(true)}
+            onClose={clearSelection}
+            onPickAction={(index) => commit(quickActionBody(quickActions[index]!))}
+            onBack={() => setActionsOpen(false)}
+            theme={theme}
+          />
+        </box>
+      ) : null}
+      {selected && composing ? (
+        <box style={overlayStyle}>
+          <AnnotationCard
+            kind="comment"
+            quote={selected.quote}
+            draft={{
+              text: draftText,
+              onInput: setDraftText,
+              onSave: () => commit(draftText),
+              onSubmit: () => commit(draftText),
+              onCancel: clearSelection,
+            }}
+            theme={theme}
+          />
+        </box>
+      ) : null}
+    </box>
+  );
+}
+
+function statusLine(status: SheetStatus, errorMessage: string): string {
+  if (status === "loading") return "rendering prototype…";
+  if (status === "unsupported")
+    return "prototype preview needs a graphics terminal (kitty or ghostty)";
+  return `prototype preview failed: ${errorMessage}`;
+}

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…                                                        │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+│                                                                              │
+╰──────────────────────────────────────────────────────────────────────────────╯
 "
 `;
 

package/src/intent-dispatch.test.ts

@@ -32,6 +32,7 @@ function baseController() {
     curationItems: mock(() => []),
     restoreCuration: mock(),
     annotate: mock(),
+    annotatePrototype: mock(),
     updateAnnotation: mock(),
     removeAnnotation: mock(),
     walkStart: mock(),

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.test.ts

@@ -0,0 +1,55 @@
+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,232 @@
+/// <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>;
+  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 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 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/session-controller.ts

@@ -197,6 +197,8 @@ export interface ReviewController {
     end: number,
     body: string,
   ): string | undefined;
+  /** Anchor a prototype comment to a DOM element by its selector. */
+  annotatePrototype(selector: string, quote: string, body: string): string | undefined;
   /** Rewrite a stored annotation's body in place (the rail-card edit). */
   updateAnnotation(id: string, body: string): void;
   removeAnnotation(id: string): void;
@@ -679,6 +681,18 @@ class Controller implements ReviewController {
     return wire.id;
   }
 
+  annotatePrototype(selector: string, quote: string, body: string): string | undefined {
+    const session = this.snapshot.session;
+    if (!session) return undefined;
+    const anchor = { quote, prefix: "", suffix: "", selector };
+    const wire = { id: newAnnotationId(), kind: "comment", anchor, body };
+    const persisted = this.client!.sessionAnnotate(session.id, wire);
+    this.apply(persisted);
+    this.mirrorAnnotation(persisted, wire);
+    this.setStatus("comment added");
+    return wire.id;
+  }
+
   updateAnnotation(id: string, body: string): void {
     const session = this.snapshot.session;
     if (!session) return;