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

package/package.json

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

package/src/App.prototype.test.tsx

@@ -34,15 +34,16 @@ const FAKE_ELEMENT: PrototypeElement = {
 };
 
 let rendered = false;
+let screenshotCount = 0;
 let scrollDeltas: number[] = [];
 const fakeRenderer: PrototypeRenderer = {
   viewport: { width: 1280, height: 800 },
   screenshot: async () => {
     rendered = true;
+    screenshotCount += 1;
     return new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
   },
   elementAt: async () => FAKE_ELEMENT,
-  highlight: async () => undefined,
   scrollBy: async (deltaY) => {
     scrollDeltas.push(deltaY);
     return true;
@@ -69,6 +70,7 @@ beforeEach(() => {
     },
   });
   rendered = false;
+  screenshotCount = 0;
   scrollDeltas = [];
   setPrototypeRendererFactory(async () => fakeRenderer);
 });
@@ -104,10 +106,14 @@ describe("prototype review", () => {
     const setup = await renderApp();
     await waitForState(setup, () => rendered);
     await settle(setup);
+    // selecting an element must not re-screenshot the page (the popover-click
+    // lag regression): the highlight is the popover, not a fresh Chromium capture
+    const screenshotsAfterLoad = screenshotCount;
 
     // Act
     await setup.mockMouse.click(6, 6);
     await waitForText(setup, "comment");
+    expect(screenshotCount).toBe(screenshotsAfterLoad);
     await clickText(setup, "comment");
     await waitForText(setup, "write a note");
     // the keymap-suppression flag must propagate before typing so keys reach the
@@ -130,6 +136,25 @@ describe("prototype review", () => {
     expect(frame).toContain("COMMENT");
   });
 
+  test("escape cancels the compose, matching the plan composer", async () => {
+    // Arrange
+    const setup = await renderApp();
+    await waitForState(setup, () => rendered);
+    await settle(setup);
+    await setup.mockMouse.click(6, 6);
+    await waitForText(setup, "comment");
+    await clickText(setup, "comment");
+    await waitForText(setup, "write a note");
+    await settle(setup);
+
+    // Act
+    await press(setup, "escape");
+
+    // Assert - the composer closes and nothing was saved
+    await waitForTextGone(setup, "write a note");
+    expect(server.core.sessionGet(session.id).annotations).toHaveLength(0);
+  });
+
   test("wheel over the preview scrolls the page down, then up, and clears a selection", async () => {
     // Arrange
     const setup = await renderApp();
@@ -140,9 +165,12 @@ describe("prototype review", () => {
     // the page moves under it)
     await setup.mockMouse.click(6, 6);
     await waitForText(setup, "comment");
+    // scrolling moves the page, so it DOES re-screenshot (unlike a click)
+    const screenshotsBeforeScroll = screenshotCount;
     await setup.mockMouse.scroll(6, 6, "down");
     await waitForState(setup, () => scrollDeltas.length === 1);
     await waitForTextGone(setup, "comment");
+    await waitForState(setup, () => screenshotCount > screenshotsBeforeScroll);
 
     // Act - scroll back up
     await setup.mockMouse.scroll(6, 6, "up");

package/src/App.tsx

@@ -9,7 +9,14 @@
  * both sides.
  */
 
-import React, { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
 import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react";
 import type { Clock, MouseEvent } from "@opentui/core";
 import { type VerdictKind } from "@cueloop/schema";
@@ -59,6 +66,7 @@ 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 { PrototypeElement } from "./prototype-browser";
 import { type ReviewRailHandle } from "./components/ReviewRail";
 import type { AgentTerminalHandle } from "./components/agent-launcher";
 import { ReviewPanel } from "./components/ReviewPanel";
@@ -134,6 +142,13 @@ export function App({
     controller.connect();
     return () => controller.close();
   }, [controller]);
+  // stable across renders so the memoized PrototypeSheet is not re-rendered by
+  // unrelated App state (status ticks, a rail-width drag)
+  const onCommentPrototype = useCallback(
+    (element: PrototypeElement, body: string) =>
+      controller.annotatePrototype(element.selector, element.quote, body),
+    [controller],
+  );
   const { session, inbox, status, toast, error, completion, editOrphanCount, walk } =
     useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
   // A shared plan you own polls for collaborator notes while it is open; the
@@ -1002,6 +1017,9 @@ export function App({
         onMouseDrag={(event: MouseEvent) => {
           if (!dividerDragging || reviewMode !== "expanded") return;
           const next = widthFromMouseColumn(event.x, terminalWidth);
+          // many raw mouse-moves land in the same column: only re-render when the
+          // width actually changes, so the drag does not reconcile per pixel
+          if (next === reviewWidthRef.current) return;
           reviewWidthRef.current = next;
           setReviewWidth(next);
         }}
@@ -1036,9 +1054,7 @@ export function App({
               prototypePath={activeSession.artifact.meta.prototypePath ?? ""}
               quickActions={quickActions}
               canComment={isOwner && !resolved}
-              onCommentElement={(element, body) =>
-                controller.annotatePrototype(element.selector, element.quote, body)
-              }
+              onCommentElement={onCommentPrototype}
               onComposingChange={setPrototypeComposing}
               hidden={menuOpen || menuDialog !== null}
             />

package/src/components/PrototypeSheet.tsx

@@ -10,7 +10,7 @@
 
 import React, { useEffect, useRef, useState } from "react";
 import type { BoxRenderable } from "@opentui/core";
-import { useRenderer } from "@opentui/react";
+import { useKeyboard, useRenderer } from "@opentui/react";
 import type { Theme } from "../theme";
 import { quickActionBody, type QuickAction } from "../config";
 import { useComponentTheme } from "./theme-context";
@@ -28,6 +28,7 @@ import {
 import {
   deleteKittyImage,
   placeKittyImage,
+  resolveTransmitMedium,
   transmitKittyImage,
   type CellRegion,
 } from "../kitty-image";
@@ -76,7 +77,46 @@ function regionOf(box: BoxRenderable | null): CellRegion | null {
   return { column: box.x, row: box.y, columns: box.width, rows: box.height };
 }
 
-export function PrototypeSheet({
+type CaptureRenderer = {
+  resolution: { width: number; height: number } | null;
+  terminalWidth: number;
+  terminalHeight: number;
+};
+
+/**
+ * Capture at the region's own pixel size when the terminal reports its cell
+ * pixels, so the terminal never downscales an oversized image (less Chromium
+ * raster and fewer bytes). Without a resolution report, fall back to a fixed
+ * width at 2x and derive the height from the cell aspect.
+ */
+function captureConfig(
+  region: CellRegion,
+  renderer: CaptureRenderer,
+): { viewport: PrototypeViewport; deviceScaleFactor: number } {
+  const resolution = renderer.resolution;
+  if (resolution && renderer.terminalWidth >= 1 && renderer.terminalHeight >= 1) {
+    const cellWidth = resolution.width / renderer.terminalWidth;
+    const cellHeight = resolution.height / renderer.terminalHeight;
+    return {
+      viewport: {
+        width: Math.max(1, Math.round(region.columns * cellWidth)),
+        height: Math.max(1, Math.round(region.rows * cellHeight)),
+      },
+      deviceScaleFactor: 1,
+    };
+  }
+  return {
+    viewport: {
+      width: CAPTURE_WIDTH,
+      height: Math.round(
+        (CAPTURE_WIDTH * region.rows * cellHeightOverWidth(renderer)) / region.columns,
+      ),
+    },
+    deviceScaleFactor: 2,
+  };
+}
+
+function PrototypeSheetImpl({
   prototypePath,
   quickActions,
   canComment,
@@ -125,6 +165,7 @@ export function PrototypeSheet({
     const rawWrite = (renderer as unknown as { writeOut?: (data: string) => void }).writeOut;
     const write =
       typeof rawWrite === "function" ? (chunk: string) => rawWrite.call(renderer, chunk) : null;
+    const medium = resolveTransmitMedium();
     const paint = (): void => {
       if (!write) return;
       // an app overlay is covering the sheet: pull the image so it does not show
@@ -140,7 +181,7 @@ export function PrototypeSheet({
       const png = pngRef.current;
       if (!region || !png) return;
       if (transmittedRef.current !== png) {
-        transmitKittyImage(write, png, region, PROTOTYPE_IMAGE_ID);
+        transmitKittyImage(write, png, region, PROTOTYPE_IMAGE_ID, medium);
         transmittedRef.current = png;
       } else {
         placeKittyImage(write, region, PROTOTYPE_IMAGE_ID);
@@ -179,16 +220,15 @@ export function PrototypeSheet({
       return;
     }
     launchedRef.current = true;
-    const viewport = {
-      width: CAPTURE_WIDTH,
-      height: Math.round(
-        (CAPTURE_WIDTH * region.rows * cellHeightOverWidth(renderer!)) / region.columns,
-      ),
-    };
-    viewportRef.current = viewport;
+    const capture = captureConfig(region, renderer!);
+    viewportRef.current = capture.viewport;
     void (async () => {
       try {
-        const browser = await prototypeRendererFactory()({ filePath: prototypePath, viewport });
+        const browser = await prototypeRendererFactory()({
+          filePath: prototypePath,
+          viewport: capture.viewport,
+          deviceScaleFactor: capture.deviceScaleFactor,
+        });
         // the sheet may have unmounted while Chromium was launching; close the
         // late arrival instead of leaking the process
         if (unmountedRef.current) {
@@ -219,12 +259,15 @@ export function PrototypeSheet({
     setActionsOpen(false);
     setComposing(false);
     setDraftText("");
-    void browserRef.current
-      ?.highlight(null)
-      .then(refresh)
-      .catch(() => undefined);
   };
 
+  // While the compose textarea owns the keyboard, the global keymap is
+  // suppressed, so escape-to-cancel is handled here - matching the plan
+  // composer, where escape closes the overlay.
+  useKeyboard((key) => {
+    if (composing && key.name === "escape") clearSelection();
+  });
+
   const onRegionMouseDown = (event: { x: number; y: number }): void => {
     const browser = browserRef.current;
     const region = regionOf(regionRef.current);
@@ -249,8 +292,6 @@ export function PrototypeSheet({
       });
       setActionsOpen(false);
       setComposing(false);
-      await browser.highlight(element.selector);
-      await refresh();
     })().catch((error) => {
       setErrorMessage(error instanceof Error ? error.message : String(error));
       setStatus("error");
@@ -350,6 +391,13 @@ export function PrototypeSheet({
   );
 }
 
+/**
+ * Memoized so an unrelated App re-render (status ticks, a rail-width drag) does
+ * not re-render the sheet; the parent passes a stable onCommentElement so the
+ * shallow prop compare holds.
+ */
+export const PrototypeSheet = React.memo(PrototypeSheetImpl);
+
 function statusLine(status: SheetStatus, errorMessage: string): string {
   if (status === "loading") return "rendering prototype…";
   if (status === "unsupported")

package/src/kitty-image.test.ts

@@ -1,9 +1,11 @@
+/** Kitty emission guards: the image sits beneath painted cells, and every put reuses one placement id so repeated frames REPLACE the placement instead of stacking a new one each frame (the prototype's per-frame lag/ghosting regression). Transmit medium is file locally and base64 over ssh. */
+
 import { describe, expect, test } from "bun:test";
-import { placeKittyImage, transmitKittyImage } from "./kitty-image";
+import { placeKittyImage, resolveTransmitMedium, transmitKittyImage } from "./kitty-image";
 
 const REGION = { column: 2, row: 3, columns: 40, rows: 12 };
 
-describe("kitty image stacking", () => {
+describe("kitty image placement", () => {
   test("places the prototype below cells with painted backgrounds", () => {
     // Arrange
     const writes: string[] = [];
@@ -17,4 +19,48 @@ describe("kitty image stacking", () => {
     expect(writes[0]).toContain("z=-1073741825");
     expect(writes[1]).toContain("z=-1073741825");
   });
+
+  test("every frame reuses one placement id, so repeated puts replace rather than stack", () => {
+    // Arrange
+    const writes: string[] = [];
+    const write = (chunk: string): void => void writes.push(chunk);
+
+    // Act - one transmit then many re-places, as the per-frame paint loop does
+    transmitKittyImage(write, new Uint8Array([1]), REGION, 811, "base64");
+    for (let frame = 0; frame < 5; frame++) placeKittyImage(write, REGION, 811);
+
+    // Assert - a stable placement id p=1 on the transmit and every place
+    expect(writes[0]).toContain("i=811,p=1");
+    for (const placement of writes.slice(1)) expect(placement).toContain("i=811,p=1");
+  });
+
+  test("base64 transmit chunks the payload; file transmit hands over a path once", () => {
+    // Arrange
+    const big = new Uint8Array(9000).fill(1);
+    const base64Writes: string[] = [];
+    const fileWrites: string[] = [];
+
+    // Act
+    transmitKittyImage((chunk) => base64Writes.push(chunk), big, REGION, 811, "base64");
+    transmitKittyImage((chunk) => fileWrites.push(chunk), big, REGION, 811, "file");
+
+    // Assert - base64 inlines the data (a=T without t=), file references a temp path (t=t)
+    expect(base64Writes[0]).toContain("a=T");
+    expect(base64Writes[0]).not.toContain("t=t");
+    expect(fileWrites[0]).toContain("t=t");
+  });
+});
+
+describe("resolveTransmitMedium", () => {
+  test("defaults to base64; file transfer is opt-in and never over ssh", () => {
+    // Assert
+    expect(resolveTransmitMedium({} as NodeJS.ProcessEnv)).toBe("base64");
+    expect(resolveTransmitMedium({ CUELOOP_KITTY_FILE: "1" } as NodeJS.ProcessEnv)).toBe("file");
+    expect(
+      resolveTransmitMedium({
+        CUELOOP_KITTY_FILE: "1",
+        SSH_CONNECTION: "1.2.3.4 5 6 7",
+      } as NodeJS.ProcessEnv),
+    ).toBe("base64");
+  });
 });

package/src/kitty-image.ts

@@ -1,11 +1,19 @@
 /**
  * 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.
+ * the screenshot itself: transmit the PNG once under a fixed image AND placement
+ * id, then re-place that same placement after each frame over its reserved
+ * (never-repainted) cells. Reusing one placement id means each frame REPLACES
+ * the placement rather than stacking a new one, which is the protocol's
+ * flicker-free move/resize path. Locally the PNG travels out of band via a
+ * temporary file so its bytes never cross the pty; a base64 fallback covers the
+ * ssh sharing path where no shared filesystem exists.
  */
 
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 export interface CellRegion {
   /** 0-based screen cell of the region's top-left corner. */
   column: number;
@@ -17,11 +25,32 @@ export interface CellRegion {
 /** Writes a raw sequence ordered against the renderer's own frame output. */
 export type OrderedWrite = (chunk: string) => void;
 
+export type TransmitMedium = "file" | "base64";
+
 const ESCAPE_STRING_TERMINATOR = "\x1b\\";
 const CHUNK_BYTES = 4096;
 // The protocol reserves values below INT32_MIN/2 for images that must sit
 // beneath cells with painted backgrounds, such as the marker popover.
 const IMAGE_Z_INDEX = -1_073_741_825;
+// One fixed placement per image: reusing it makes every put replace that
+// placement instead of accumulating a new one each frame.
+const PLACEMENT_ID = 1;
+const SYNCHRONIZED_UPDATE_START = "\x1b[?2026h";
+const SYNCHRONIZED_UPDATE_END = "\x1b[?2026l";
+
+let tempFileCounter = 0;
+let privateTempDir: string | null = null;
+
+/**
+ * base64 is the safe default: it works over the pty everywhere, including the
+ * ssh sharing path. Out-of-band file transfer (t=t) is faster for the initial
+ * transmit but depends on the terminal trusting the temp-file path, so it is
+ * opt-in via `CUELOOP_KITTY_FILE=1` and never used over ssh (no shared disk).
+ */
+export function resolveTransmitMedium(env: NodeJS.ProcessEnv = process.env): TransmitMedium {
+  if (env.CUELOOP_KITTY_FILE === "1" && !env.SSH_CONNECTION && !env.SSH_TTY) return "file";
+  return "base64";
+}
 
 /** Save the cursor, run the placement at the region's corner, restore it. */
 function atRegion(region: CellRegion, body: string): string {
@@ -33,40 +62,65 @@ function graphicsCommand(keys: string, payload: string): string {
   return `\x1b_G${keys};${payload}${ESCAPE_STRING_TERMINATOR}`;
 }
 
+function placementKeys(imageId: number, region: CellRegion): string {
+  return `i=${imageId},p=${PLACEMENT_ID},q=2,C=1,z=${IMAGE_Z_INDEX},c=${region.columns},r=${region.rows}`;
+}
+
+// A per-process 0700 directory with an unpredictable name, so a local attacker
+// cannot pre-place a symlink at the screenshot path and redirect the write.
+function writeTempPng(png: Uint8Array): string {
+  if (!privateTempDir) privateTempDir = mkdtempSync(join(tmpdir(), "cueloop-prototype-"));
+  const path = join(privateTempDir, `${tempFileCounter++}.png`);
+  writeFileSync(path, png, { flag: "wx" });
+  return path;
+}
+
+function base64Transmit(png: Uint8Array, region: CellRegion, imageId: number): string {
+  const base64 = Buffer.from(png).toString("base64");
+  const controlKeys = `a=T,f=100,${placementKeys(imageId, region)}`;
+  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);
+  }
+  return sequence;
+}
+
+function fileTransmit(png: Uint8Array, region: CellRegion, imageId: number): string {
+  const path = writeTempPng(png);
+  const payload = Buffer.from(path).toString("base64");
+  return graphicsCommand(`a=T,f=100,t=t,${placementKeys(imageId, region)}`, payload);
+}
+
 /**
  * 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.
+ * q=2 suppresses the terminal's replies. The whole write is bracketed in
+ * synchronized-update mode so the terminal composites it atomically. `file`
+ * hands over a temp path (t=t: the terminal deletes it after reading); `base64`
+ * inlines the data, chunked at 4096 bytes.
  */
 export function transmitKittyImage(
   write: OrderedWrite,
   png: Uint8Array,
   region: CellRegion,
   imageId: number,
+  medium: TransmitMedium = "base64",
 ): void {
   if (region.columns < 1 || region.rows < 1) return;
-  const base64 = Buffer.from(png).toString("base64");
-  const controlKeys = `a=T,f=100,i=${imageId},q=2,C=1,z=${IMAGE_Z_INDEX},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));
+  const body =
+    medium === "file" ? fileTransmit(png, region, imageId) : base64Transmit(png, region, imageId);
+  write(SYNCHRONIZED_UPDATE_START + atRegion(region, body) + SYNCHRONIZED_UPDATE_END);
 }
 
-/** Re-place an already-transmitted image over its region, cheaply (a=p, no data). */
+/** Re-place the 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=${IMAGE_Z_INDEX},c=${region.columns},r=${region.rows}`,
-    "",
-  );
-  write(atRegion(region, command));
+  write(atRegion(region, graphicsCommand(`a=p,${placementKeys(imageId, region)}`, "")));
 }
 
 /** Remove the image so it does not linger after the sheet closes (a=d). */

package/src/prototype-browser.ts

@@ -30,7 +30,6 @@ 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>;
@@ -39,6 +38,8 @@ export interface PrototypeRenderer {
 export interface LaunchOptions {
   filePath: string;
   viewport: PrototypeViewport;
+  /** Capture density; 1 when the viewport already matches the region's pixels. */
+  deviceScaleFactor?: number;
   /** Absolute path to a Chrome/Chromium binary; falls back to the channel. */
   executablePath?: string;
 }
@@ -95,30 +96,54 @@ export function prototypeRendererFactory(): PrototypeRendererFactory {
   return rendererFactory ?? launchPrototypeRenderer;
 }
 
-export async function launchPrototypeRenderer(options: LaunchOptions): Promise<PrototypeRenderer> {
+type PuppeteerBrowser = Awaited<ReturnType<typeof import("puppeteer-core").default.launch>>;
+
+// One Chromium per process, kept warm and reused across prototype opens: the
+// launch is the dominant load cost, so each open only spawns a fresh page.
+let sharedBrowser: Promise<PuppeteerBrowser> | null = null;
+
+async function warmBrowser(executablePath: string | undefined): Promise<PuppeteerBrowser> {
+  // reuse the warm browser only while it is still connected; a crashed or
+  // disconnected Chromium is dropped so the next open relaunches instead of
+  // calling newPage on a dead process forever
+  const cached = sharedBrowser ? await sharedBrowser.catch(() => null) : null;
+  if (cached && cached.connected) return cached;
   const puppeteer = (await import("puppeteer-core")).default;
-  const { pathToFileURL } = await import("node:url");
-  const browser = await puppeteer.launch({
-    executablePath: options.executablePath ?? chromeExecutable(),
+  const launched = puppeteer.launch({
+    executablePath: 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();
+  sharedBrowser = launched;
+  const browser = await launched.catch((error) => {
+    if (sharedBrowser === launched) sharedBrowser = null;
     throw error;
   });
-  await page
-    .goto(pathToFileURL(options.filePath).href, { waitUntil: "networkidle0" })
-    .catch(async (error) => {
-      await browser.close();
-      throw error;
+  browser.once("disconnected", () => {
+    if (sharedBrowser === launched) sharedBrowser = null;
+  });
+  return browser;
+}
+
+export async function launchPrototypeRenderer(options: LaunchOptions): Promise<PrototypeRenderer> {
+  const { pathToFileURL } = await import("node:url");
+  const browser = await warmBrowser(options.executablePath);
+  // close only the page on teardown, never the shared browser, so the next open
+  // reuses the warm Chromium
+  const page = await browser.newPage();
+  try {
+    await page.setViewport({
+      width: options.viewport.width,
+      height: options.viewport.height,
+      deviceScaleFactor: options.deviceScaleFactor ?? 2,
     });
+    // `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" });
+  } catch (error) {
+    await page.close().catch(() => undefined);
+    throw error;
+  }
 
   return {
     viewport: options.viewport,
@@ -129,14 +154,11 @@ export async function launchPrototypeRenderer(options: LaunchOptions): Promise<P
     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();
+      await page.close().catch(() => undefined);
     },
   };
 }
@@ -212,25 +234,6 @@ function scrollByScript(deltaY: number): boolean {
   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") {