@cueloop/client 0.1.0-alpha.7 → 0.1.0-alpha.71

package/src/keymap.ts

@@ -0,0 +1,410 @@
+/**
+ * The keyboard grammar as a pure reducer: view state in, intents out.
+ * App builds a KeyState per key event, calls reduceKey, and dispatches the
+ * intents to controller primitives and view-state setters - no branch bodies live
+ * in the key handler. Diff and plan reviews share one path for annotation
+ * navigation, deletion, and submit; the read-only rule is one gate here.
+ */
+
+import { actionFor } from "./config";
+
+export type Intent =
+  | { type: "exit" }
+  | { type: "status"; message: string }
+  | { type: "move"; to: "down" | "up" | "top" | "bottom" }
+  | { type: "inboxMove"; to: "down" | "up" }
+  | { type: "openSession" }
+  | { type: "requestDeleteSession" }
+  | { type: "openRename" }
+  | { type: "confirmDialog" }
+  | { type: "startSpan" }
+  | { type: "spanKey"; name: string }
+  | { type: "spanCut" }
+  | { type: "openSpanActions" }
+  | { type: "moveSpanAction"; direction: -1 | 1 }
+  | { type: "pickSpanAction"; index?: number }
+  | { type: "closeSpanActions" }
+  | { type: "openCompose"; kind: "comment"; from: "cursor" | "span" }
+  | { type: "openSubmit" }
+  | { type: "share" }
+  | { type: "cut" }
+  | { type: "edit" }
+  | { type: "editCard" }
+  | { type: "rejectHunk" }
+  | { type: "rejectChange" }
+  | { type: "restoreCuration" }
+  | { type: "foldFile" }
+  | { type: "unfoldFile" }
+  | { type: "toggleDiffView" }
+  | { type: "nextAnnotation" }
+  | { type: "prevAnnotation" }
+  | { type: "walkStart" }
+  | { type: "walkForward" }
+  | { type: "walkBack" }
+  | { type: "walkLeave" }
+  | { type: "removeAnnotation" }
+  | { type: "deselect" }
+  | { type: "closeOverlay" }
+  | { type: "saveCompose" }
+  | { type: "submitVerdict" }
+  | { type: "cycleVerdict"; direction: -1 | 1 }
+  | { type: "finishReview" }
+  | { type: "optInAutoClose" }
+  | { type: "dismissCompletion" }
+  | { type: "toggleTree" }
+  | { type: "treeMove"; direction: -1 | 1 }
+  | { type: "treeGo" }
+  | { type: "treeBranch" }
+  | { type: "treeLabel" }
+  | { type: "treeFork" }
+  | { type: "treeForkShare" };
+
+export interface KeyInput {
+  name: string;
+  shift: boolean;
+  /** Option/Alt arrives as `meta` in this terminal stack (never as a raw alt). */
+  meta?: boolean;
+}
+
+export interface KeyState {
+  /** Loaded keymap (config.ts): action -> key combos. */
+  keys: Record<string, string[]>;
+  readOnly: boolean;
+  /**
+   * Owner-only primitives a share collaborator lacks (undefined = owner, allowed).
+   * A collaborator annotates but cannot edit the plan (cut / $EDITOR runs on
+   * the gateway) or submit an agent verdict (there is no agent on a share).
+   */
+  canEditPlan?: boolean;
+  canSubmitVerdict?: boolean;
+  /** Owner-only: publish the plan as a share. A collaborator never re-shares. */
+  canShare?: boolean;
+  /** Layer that owns keys before the grammar runs. */
+  overlay:
+    | "none"
+    | "walk"
+    | "compose"
+    | "submit"
+    | "confirm"
+    | "prompt"
+    | "spanActions"
+    | "completion-prompt"
+    | "completion-counting";
+  view: "inbox" | "plan" | "diff";
+  /** Plan-only span selection sub-mode. */
+  spanMode: boolean;
+  /** The walk cursor sits on the end card - return offers the submit action. */
+  walkAtEnd: boolean;
+  resolved: boolean;
+  hasInboxItems: boolean;
+  annotationCount: number;
+  hasFocusedAnnotation: boolean;
+  /** Cursor sits on annotatable text: a work block (plan) or a code row (diff). */
+  cursorAnnotatable: boolean;
+}
+
+/** Primitives that write session state; an observer never reaches their handlers. */
+const MUTATING_ACTIONS = new Set([
+  "comment",
+  "cut",
+  "edit",
+  "delete_annotation",
+  "submit",
+  "walk",
+  "share",
+  "reject_hunk",
+  "restore_curation",
+]);
+
+const SPAN_KEYS = new Set(["l", "h", "w", "b", "$", "0"]);
+
+function status(message: string): Intent[] {
+  return [{ type: "status", message }];
+}
+
+/**
+ * Reduce one key event to intents. `resolvedAction` is the binding-layer
+ * resolution (key-bindings.ts over @opentui/keymap) when the caller has one;
+ * without it the reducer falls back to the plain reverse lookup, so the
+ * grammar stays testable as a pure function.
+ */
+export function reduceKey(state: KeyState, key: KeyInput, resolvedAction?: string): Intent[] {
+  const name = key.name;
+  const overlayGrammar = overlayGrammars[state.overlay];
+
+  if (overlayGrammar) return overlayGrammar(state, key);
+  const action = resolvedAction ?? actionFor(state.keys, name, key.shift);
+
+  if (action === "quit") return [{ type: "exit" }];
+  // the ONE read-only rule: any mutating attempt answers instead of acting
+  // (span-mode c, x, and a are hardwired keys, so they gate by name as well)
+  const mutating =
+    MUTATING_ACTIONS.has(action ?? "") ||
+    (state.spanMode && (name === "c" || name === "x" || name === "a"));
+
+  if (state.readOnly && mutating) return status("observer - read-only");
+
+  // share is a session-level primitive: it works from any view, owner only
+  if (action === "share") {
+    if (state.canShare === false) return status("only the plan owner can share");
+
+    return [{ type: "share" }];
+  }
+
+  if (state.view === "inbox") return inboxGrammar(state, name);
+  // span mode owns its single-letter keys (b slides the span back)
+  if (state.spanMode) return spanGrammar(state, name);
+  if (state.view === "diff") return diffGrammar(state, action);
+
+  return planGrammar(state, action, name);
+}
+
+type OverlayGrammar = (state: KeyState, key: KeyInput) => Intent[];
+
+const overlayGrammars: Partial<Record<KeyState["overlay"], OverlayGrammar>> = {
+  compose: composeOverlayGrammar,
+  submit: submitOverlayGrammar,
+  confirm: confirmOverlayGrammar,
+  prompt: promptOverlayGrammar,
+  spanActions: spanActionsOverlayGrammar,
+  "completion-prompt": completionOverlayGrammar,
+  "completion-counting": completionOverlayGrammar,
+  walk: walkOverlayGrammar,
+};
+
+function composeOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (name === "return" || name === "enter") {
+    // In the composer, ⌥/Alt+⏎ (meta) and shift+⏎ insert a newline - the
+    // focused textarea owns that; only a bare ⏎ saves. The submit overlay
+    // keeps its plain ⏎ submit.
+    if (key.shift || key.meta) return [];
+
+    return [{ type: "saveCompose" }];
+  }
+
+  return [];
+}
+
+function submitOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (name === "return" || name === "enter") return [{ type: "submitVerdict" }];
+  if (name === "left" || name === "right") {
+    return [{ type: "cycleVerdict", direction: name === "left" ? -1 : 1 }];
+  }
+
+  return [];
+}
+
+function confirmOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter") return [{ type: "confirmDialog" }];
+  if (name === "escape") return [{ type: "closeOverlay" }];
+
+  return [];
+}
+
+function promptOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter") return [{ type: "confirmDialog" }];
+  if (name === "escape") return [{ type: "closeOverlay" }];
+
+  return [];
+}
+
+function spanActionsOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "j" || name === "down") return [{ type: "moveSpanAction", direction: 1 }];
+  if (name === "k" || name === "up") return [{ type: "moveSpanAction", direction: -1 }];
+  if (name === "return" || name === "enter") return [{ type: "pickSpanAction" }];
+  if (name === "escape") return [{ type: "closeSpanActions" }];
+
+  return [];
+}
+
+function completionOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "return" || name === "enter" || name === "q") return [{ type: "finishReview" }];
+  if (name === "a") return [{ type: "optInAutoClose" }];
+  if (name === "escape") return [{ type: "dismissCompletion" }];
+
+  return [];
+}
+
+function walkOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
+  const name = key.name;
+
+  if (name === "]") return [{ type: "walkForward" }];
+  if (name === "[") return [{ type: "walkBack" }];
+  if (name === "escape") return [{ type: "walkLeave" }];
+  if ((name === "return" || name === "enter") && state.walkAtEnd) {
+    return [{ type: "walkLeave" }, { type: "openSubmit" }];
+  }
+  if (name === "q") return [{ type: "exit" }];
+
+  return [];
+}
+
+function inboxGrammar(state: KeyState, name: string): Intent[] {
+  if (!state.hasInboxItems) return [];
+  if (name === "j" || name === "down") return [{ type: "inboxMove", to: "down" }];
+  if (name === "k" || name === "up") return [{ type: "inboxMove", to: "up" }];
+  if (name === "return" || name === "enter") return [{ type: "openSession" }];
+  if (name === "d") return [{ type: "requestDeleteSession" }];
+
+  return [];
+}
+
+function diffGrammar(state: KeyState, action: string | undefined): Intent[] {
+  const navigation = navigationIntent(action);
+
+  if (navigation) return navigation;
+  if (action === "walk") {
+    // marking viewed writes the session record, so a resolved review answers
+    if (state.resolved) return status("review submitted - read-only");
+
+    return [{ type: "walkStart" }];
+  }
+  if (action === "comment") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (!state.cursorAnnotatable) return status("move to a code line to comment");
+
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  // cut rejects the change under the cursor, reject_hunk the whole hunk; both
+  // write the working copy, so they gate on owner like a plan edit.
+  if (action === "cut" || action === "reject_hunk") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return status("only the diff owner can curate hunks");
+
+    return [{ type: action === "reject_hunk" ? "rejectHunk" : "rejectChange" }];
+  }
+  const viewToggle = viewToggleIntent(action);
+
+  if (viewToggle) return viewToggle;
+  // restore un-does a curated-out rejection from the rail; same owner gate as reject
+  if (action === "restore_curation") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return status("only the diff owner can curate hunks");
+
+    return [{ type: "restoreCuration" }];
+  }
+  const shared = annotationCluster(state, action);
+
+  if (shared) return shared;
+  if (action === "span" || action === "edit") {
+    return status("plan-only primitive - diff review uses c on a line");
+  }
+
+  return [];
+}
+
+function spanGrammar(state: KeyState, name: string): Intent[] {
+  if (name === "escape") return [{ type: "closeOverlay" }];
+  if (SPAN_KEYS.has(name)) return [{ type: "spanKey", name }];
+  // c comments, x cuts, a opens quick-actions - all mutate, so a resolved
+  // review is read-only, like the plan grammar
+  if (name === "c" || name === "x" || name === "a") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (name === "c") return [{ type: "openCompose", kind: "comment", from: "span" }];
+    if (name === "a") return [{ type: "openSpanActions" }];
+    // partial-span cut is not in the working-copy model, so cut removes the
+    // whole block the span sits in; owner-only, like plan cut
+    if (state.canEditPlan === false) return [];
+
+    return [{ type: "spanCut" }];
+  }
+
+  return [];
+}
+
+function planGrammar(state: KeyState, action: string | undefined, name: string): Intent[] {
+  const navigation = navigationIntent(action);
+
+  if (navigation) return navigation;
+  if (action === "walk") return status("the guided walk is a diff-review mode");
+  if (name === "escape") return [{ type: "deselect" }];
+  if (action === "span") return state.cursorAnnotatable ? [{ type: "startSpan" }] : [];
+  if (action === "comment") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (!state.cursorAnnotatable) return status("text is cut - restore it first");
+
+    return [{ type: "openCompose", kind: "comment", from: "cursor" }];
+  }
+  // restore un-does a rail removal (a cut block); a plan edit, so owner-only
+  if (action === "restore_curation") {
+    if (state.resolved) return status("review submitted - read-only");
+    if (state.canEditPlan === false) return [];
+
+    return [{ type: "restoreCuration" }];
+  }
+  if (action === "cut" || action === "edit") {
+    if (state.resolved) return status("review submitted - read-only");
+    // the document selects, the rail edits: with a card selected, Cut deletes
+    // the annotation and edit rewrites the card body in place
+    if (state.hasFocusedAnnotation)
+      return [action === "cut" ? { type: "removeAnnotation" } : { type: "editCard" }];
+    // editing the plan itself is the owner's primitive; a share viewer only annotates,
+    // and has no edit affordance, so the key is silent rather than a nag
+    if (state.canEditPlan === false) return [];
+
+    return [{ type: action }];
+  }
+
+  return annotationCluster(state, action) ?? [];
+}
+
+/** Cursor movement is the same intent everywhere; views clamp their own bounds. */
+function navigationIntent(action: string | undefined): Intent[] | null {
+  if (action === "down" || action === "up" || action === "top" || action === "bottom") {
+    return [{ type: "move", to: action }];
+  }
+
+  return null;
+}
+
+/** Ungated view toggles in the diff: right folds a file to its band, left unfolds it, s flips
+ *  split/stacked (split lays out only when the Changes pane is wide/zoomed). */
+function viewToggleIntent(action: string | undefined): Intent[] | null {
+  if (action === "collapse_file") return [{ type: "foldFile" }];
+  if (action === "expand_file") return [{ type: "unfoldFile" }];
+  if (action === "split_diff") return [{ type: "toggleDiffView" }];
+
+  return null;
+}
+
+/** Annotation navigation, deletion, and submit: one path for plan and diff. */
+function annotationCluster(state: KeyState, action: string | undefined): Intent[] | null {
+  if (action === "next_annotation" || action === "prev_annotation") {
+    if (!state.annotationCount) return status("no annotations");
+
+    return [{ type: action === "next_annotation" ? "nextAnnotation" : "prevAnnotation" }];
+  }
+  if (action === "delete_annotation") {
+    if (state.resolved || !state.hasFocusedAnnotation) return [];
+
+    return [{ type: "removeAnnotation" }];
+  }
+  if (action === "rename") {
+    if (!state.hasFocusedAnnotation) return status("select a collaborator's note to rename them");
+
+    return [{ type: "openRename" }];
+  }
+  if (action === "submit") {
+    // a collaborator's notes union back as they go; there is no verdict to submit
+    if (state.canSubmitVerdict === false)
+      return status("shared view - your notes save as you go; q to leave");
+
+    return state.resolved ? [] : [{ type: "openSubmit" }];
+  }
+
+  return null;
+}

package/src/kitty-image.test.ts

@@ -0,0 +1,66 @@
+/** 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, resolveTransmitMedium, transmitKittyImage } from "./kitty-image";
+
+const REGION = { column: 2, row: 3, columns: 40, rows: 12 };
+
+describe("kitty image placement", () => {
+  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");
+  });
+
+  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({})).toBe("base64");
+    expect(resolveTransmitMedium({ CUELOOP_KITTY_FILE: "1" })).toBe("file");
+    expect(
+      resolveTransmitMedium({
+        CUELOOP_KITTY_FILE: "1",
+        SSH_CONNECTION: "1.2.3.4 5 6 7",
+      }),
+    ).toBe("base64");
+  });
+});

package/src/kitty-image.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 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;
+  row: number;
+  columns: number;
+  rows: number;
+}
+
+/** 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 {
+  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}`;
+}
+
+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. 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 body =
+    medium === "file" ? fileTransmit(png, region, imageId) : base64Transmit(png, region, imageId);
+
+  write(SYNCHRONIZED_UPDATE_START + atRegion(region, body) + SYNCHRONIZED_UPDATE_END);
+}
+
+/** 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;
+  write(atRegion(region, graphicsCommand(`a=p,${placementKeys(imageId, region)}`, "")));
+}
+
+/** 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`, ""));
+}