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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cueloop/client",
-  "version": "0.1.0-alpha.45",
+  "version": "0.1.0-alpha.46",
   "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.46",
+    "@cueloop/extension-api": "0.1.0-alpha.46",
+    "@cueloop/integration-obsidian": "0.1.0-alpha.46",
+    "@cueloop/schema": "0.1.0-alpha.46",
     "@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.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,7 @@ export function App({
   }, [marks]);
   const resolved = session?.status === "resolved";
   const isDiff = session?.artifact.type === "diff";
+  const isPrototype = session?.artifact.type === "prototype";
   // 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
@@ -1025,7 +1027,16 @@ 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)
+              }
+            />
+          ) : isDiff ? (
             // the sheet dims to reading-quiet colors while the wizard has focus
             <DiffSheet
               rows={rows}
@@ -1061,7 +1072,7 @@ export function App({
               session: activeSession,
               authorNames,
               selectedId: focusedAnnotationId,
-              resolvedIds: isDiff ? null : resolvedIds,
+              resolvedIds: isDiff || isPrototype ? null : resolvedIds,
               curationItems,
               selectedCurationId,
               annotationPositions,

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,228 @@
+/**
+ * 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.
+ */
+
+import React, { useEffect, useRef, useState } from "react";
+import type { ImageRenderable } 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,
+  launchPrototypeRenderer,
+  type PrototypeElement,
+  type PrototypeRenderer,
+  type PrototypeViewport,
+} from "../prototype-browser";
+
+export interface PrototypeSheetProps {
+  prototypePath: string;
+  quickActions: QuickAction[];
+  canComment: boolean;
+  onCommentElement: (element: PrototypeElement, body: string) => void;
+  theme?: Theme;
+}
+
+type SheetStatus = "loading" | "ready" | "unsupported" | "error";
+
+const DEFAULT_CELL_ASPECT = 2;
+const POPOVER_ROWS = 3;
+
+export function PrototypeSheet({
+  prototypePath,
+  quickActions,
+  canComment,
+  onCommentElement,
+  theme,
+}: PrototypeSheetProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const renderer = useRenderer();
+  const imageRef = useRef<ImageRenderable | null>(null);
+  const browserRef = useRef<PrototypeRenderer | null>(null);
+  const launchedRef = useRef(false);
+  const viewportRef = useRef<PrototypeViewport>({ width: 1280, height: 800 });
+
+  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("");
+
+  useEffect(() => {
+    return () => {
+      void browserRef.current?.close();
+    };
+  }, []);
+
+  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 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) {
+      setStatus("unsupported");
+      return;
+    }
+    launchedRef.current = true;
+    const viewport = viewportFor(image.width, image.height);
+    viewportRef.current = viewport;
+    void (async () => {
+      try {
+        const browser = await launchPrototypeRenderer({ filePath: prototypePath, viewport });
+        browserRef.current = browser;
+        setPng(await browser.screenshot());
+        setStatus("ready");
+      } catch (error) {
+        setErrorMessage(error instanceof Error ? error.message : String(error));
+        setStatus("error");
+      }
+    })();
+  };
+
+  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 onImageMouseDown = (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 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 overlayLeft = overlayCell?.left ?? 0;
+  const overlayTop = Math.max(0, overlayCell?.top ?? 0);
+  const overlayStyle = {
+    position: "absolute" as const,
+    left: overlayLeft,
+    top: overlayTop,
+    flexDirection: "column" as const,
+  };
+
+  return (
+    <box
+      style={{
+        flexGrow: 1,
+        flexDirection: "column",
+        border: true,
+        borderStyle: FRAME_BORDER_STYLE,
+        borderColor: tokens.text,
+      }}
+    >
+      <image
+        ref={(instance: ImageRenderable | null) => {
+          imageRef.current = instance;
+        }}
+        {...(png ? { source: png } : {})}
+        fit="fill"
+        protocol="auto"
+        style={{ flexGrow: 1 }}
+        onSizeChange={launch}
+        onMouseDown={onImageMouseDown}
+      />
+      {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={() => (canComment ? setComposing(true) : undefined)}
+            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),
+              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

@@ -1825,5 +1825,33 @@ 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/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/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,218 @@
+/// <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 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;