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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.47",
+  "version": "0.1.0-alpha.49",
   "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.47",
-    "@cueloop/extension-api": "0.1.0-alpha.47",
-    "@cueloop/integration-obsidian": "0.1.0-alpha.47",
-    "@cueloop/schema": "0.1.0-alpha.47",
+    "@cueloop/daemon": "0.1.0-alpha.49",
+    "@cueloop/extension-api": "0.1.0-alpha.49",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.49",
+    "@cueloop/schema": "0.1.0-alpha.49",
     "@opentui/core": "^0.5.2",
     "@opentui/keymap": "0.5.2",
     "@opentui/react": "^0.5.2",

package/src/App.prototype.test.tsx

@@ -21,6 +21,7 @@ import {
   typeText,
   waitForState,
   waitForText,
+  waitForTextGone,
 } from "./test-support";
 
 const HTML = "<main><div class='card'><h2>Pro</h2><p>$24/mo</p></div></main>";
@@ -33,6 +34,7 @@ const FAKE_ELEMENT: PrototypeElement = {
 };
 
 let rendered = false;
+let scrollDeltas: number[] = [];
 const fakeRenderer: PrototypeRenderer = {
   viewport: { width: 1280, height: 800 },
   screenshot: async () => {
@@ -41,6 +43,10 @@ const fakeRenderer: PrototypeRenderer = {
   },
   elementAt: async () => FAKE_ELEMENT,
   highlight: async () => undefined,
+  scrollBy: async (deltaY) => {
+    scrollDeltas.push(deltaY);
+    return true;
+  },
   close: async () => undefined,
 };
 
@@ -63,6 +69,7 @@ beforeEach(() => {
     },
   });
   rendered = false;
+  scrollDeltas = [];
   setPrototypeRendererFactory(async () => fakeRenderer);
 });
 afterEach(() => {
@@ -122,4 +129,27 @@ describe("prototype review", () => {
     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

@@ -1040,6 +1040,7 @@ export function App({
                 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/PrototypeSheet.tsx

@@ -40,6 +40,9 @@ export interface PrototypeSheetProps {
   /** 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;
 }
 
@@ -47,6 +50,8 @@ type SheetStatus = "loading" | "ready" | "unsupported" | "error";
 
 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
@@ -77,6 +82,7 @@ export function PrototypeSheet({
   canComment,
   onCommentElement,
   onComposingChange,
+  hidden = false,
   theme,
 }: PrototypeSheetProps): React.ReactNode {
   const tokens = useComponentTheme(theme);
@@ -89,6 +95,10 @@ export function PrototypeSheet({
   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>("");
@@ -117,6 +127,15 @@ export function PrototypeSheet({
       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;
@@ -238,17 +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();
   };
 
+  // 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: overlayCell?.left ?? 0,
     top: Math.max(0, overlayCell?.top ?? 0),
     flexDirection: "column" as const,
+    backgroundColor: tokens.elevated,
   };
 
   return (
@@ -268,6 +302,7 @@ export function PrototypeSheet({
         style={{ flexGrow: 1 }}
         onSizeChange={launch}
         onMouseDown={onRegionMouseDown}
+        onMouseScroll={onRegionScroll}
       />
       {status !== "ready" ? (
         <box style={{ position: "absolute", left: 2, top: 1 }}>

package/src/kitty-image.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { placeKittyImage, transmitKittyImage } from "./kitty-image";
+
+const REGION = { column: 2, row: 3, columns: 40, rows: 12 };
+
+describe("kitty image stacking", () => {
+  test("places the prototype below cells with painted backgrounds", () => {
+    // Arrange
+    const writes: string[] = [];
+
+    // Act
+    transmitKittyImage((chunk) => writes.push(chunk), new Uint8Array([1]), REGION, 811);
+    placeKittyImage((chunk) => writes.push(chunk), REGION, 811);
+
+    // Assert
+    expect(writes).toHaveLength(2);
+    expect(writes[0]).toContain("z=-1073741825");
+    expect(writes[1]).toContain("z=-1073741825");
+  });
+});

package/src/kitty-image.ts

@@ -19,6 +19,9 @@ export type OrderedWrite = (chunk: string) => void;
 
 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;
 
 /** Save the cursor, run the placement at the region's corner, restore it. */
 function atRegion(region: CellRegion, body: string): string {
@@ -43,9 +46,7 @@ export function transmitKittyImage(
 ): 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}`;
+  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);
@@ -62,7 +63,7 @@ export function transmitKittyImage(
 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}`,
+    `a=p,i=${imageId},q=2,C=1,z=${IMAGE_Z_INDEX},c=${region.columns},r=${region.rows}`,
     "",
   );
   write(atRegion(region, command));

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>;
 }
 
@@ -130,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();
     },
@@ -201,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";