usecomputer 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,43 @@
 
 All notable changes to `usecomputer` will be documented in this file.
 
+## 0.1.3
+
+1. **Kitty Graphics Protocol support** — `screenshot` can now emit the PNG image
+   inline to stdout using the [Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
+   Set `AGENT_GRAPHICS=kitty` and the image lands directly in the AI model's context
+   window — no separate file-read tool call needed:
+
+   ```bash
+   AGENT_GRAPHICS=kitty usecomputer screenshot ./shot.png --json
+   # JSON output: { ..., "agentGraphics": true }
+   ```
+
+   Works out of the box with [kitty-graphics-agent](https://github.com/remorses/kitty-graphics-agent),
+   an OpenCode plugin that intercepts the escape sequences and injects them as
+   LLM-visible image attachments. Add it to `opencode.json` to enable:
+
+   ```json
+   { "plugin": ["kitty-graphics-agent"] }
+   ```
+
+   The plugin sets `AGENT_GRAPHICS=kitty` automatically. `agentGraphics` in the
+   JSON output is `true` only when emission actually succeeded.
+
+2. **Aligned table output for list commands** — `display list`, `window list`, and
+   `desktop list` now render as aligned, human-readable tables (matching the format
+   the old TypeScript CLI produced). JSON mode (`--json`) is unchanged:
+
+   ```
+   desktop  primary  size        position  id  scale  name
+   0        yes      3440x1440   0,0       5   1      Display 5
+   1        no       1512x982    3440,458  1   1      Display 1
+   ```
+
+3. **Fixed `agentGraphics` JSON field** — the field now reflects actual Kitty
+   emission success rather than just whether `AGENT_GRAPHICS=kitty` was set.
+   Empty PNG files and I/O errors report `false` instead of `true`.
+
 ## 0.1.2
 
 1. **Removed all unimplemented command stubs** — 18 placeholder commands (`snapshot`, `get text/title/value/bounds/focused`, `window focus/resize/move/minimize/maximize/close`, `app list/launch/quit`, `wait`, `find`, `diff snapshot/screenshot`) that only threw "TODO not implemented" have been removed. The CLI now only exposes commands that actually work.

package/README.md

@@ -2,18 +2,12 @@
 
 # usecomputer
 
-`usecomputer` is a macOS desktop automation CLI for AI agents.
+`usecomputer` is a desktop automation CLI for AI agents. It works on macOS and
+Linux (X11).
 
-It can move the mouse, click, drag, and query cursor position using native
-Quartz events through a Zig N-API module.
-
-Keyboard synthesis (`type` and `press`) is also available. The native backend
-includes platform-specific key injection paths for macOS, Windows, and Linux
-X11.
-
-The package also exports the native commands as plain library functions, so you
-can `import * as usecomputer from "usecomputer"` and reuse the same screenshot,
-mouse, keyboard, and coord-map behavior from Node.js.
+Screenshot, mouse control (move, click, drag, scroll), and keyboard synthesis
+(`type` and `press`) are all available as CLI commands backed by a native Zig
+binary — no Node.js runtime required.
 
 ## Install
 
@@ -23,8 +17,8 @@ npm install -g usecomputer
 
 ## Requirements
 
-- macOS (Darwin)
-- Accessibility permission enabled for your terminal app
+- **macOS** — Accessibility permission enabled for your terminal app
+- **Linux** — X11 session with `DISPLAY` set (Wayland via XWayland works too)
 
 ## Quick start
 
@@ -303,6 +297,32 @@ targeting:
 usecomputer debug-point -x 400 -y 220 --coord-map "0,0,1600,900,1568,882"
 ```
 
+## Kitty Graphics Protocol (agent-friendly screenshots)
+
+When the `AGENT_GRAPHICS` environment variable contains `kitty`, the
+`screenshot` command emits the PNG image inline to stdout using the
+[Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).
+This lets AI agents receive screenshots in a single tool call — no separate
+file read needed.
+
+The protocol is supported by [kitty-graphics-agent](https://github.com/remorses/kitty-graphics-agent),
+an OpenCode plugin that intercepts Kitty Graphics escape sequences from CLI
+output and injects them as LLM-visible image attachments. To use it, add the
+plugin to your `opencode.json`:
+
+```json
+{
+  "plugin": ["kitty-graphics-agent"]
+}
+```
+
+The plugin sets `AGENT_GRAPHICS=kitty` in the shell environment automatically.
+When the agent runs `usecomputer screenshot`, the image appears directly in the
+model's context window.
+
+The JSON output includes `"agentGraphics": true` when the image was emitted
+inline, so programmatic consumers know the screenshot is already in context.
+
 ## Keyboard commands
 
 ### Type text

package/bin.sh

@@ -0,0 +1,49 @@
+#!/bin/sh
+# Shell launcher for usecomputer — runs the native Zig binary for the current platform.
+
+set -e
+
+# Resolve the real directory where this script lives (follows symlinks)
+SCRIPT="$0"
+while [ -L "$SCRIPT" ]; do
+  SCRIPT_DIR="$(cd "$(dirname "$SCRIPT")" && pwd)"
+  SCRIPT="$(readlink "$SCRIPT")"
+  # Handle relative symlink targets
+  case "$SCRIPT" in
+    /*) ;;
+    *) SCRIPT="$SCRIPT_DIR/$SCRIPT" ;;
+  esac
+done
+SCRIPT_DIR="$(cd "$(dirname "$SCRIPT")" && pwd)"
+
+# Detect platform and architecture
+OS="$(uname -s)"
+ARCH="$(uname -m)"
+
+case "$OS" in
+  Darwin) PLATFORM="darwin" ;;
+  Linux)  PLATFORM="linux" ;;
+  MINGW*|MSYS*|CYGWIN*) PLATFORM="win32" ;;
+  *) echo "error: unsupported platform: $OS" >&2; exit 1 ;;
+esac
+
+case "$ARCH" in
+  arm64|aarch64) ARCH_NAME="arm64" ;;
+  x86_64|amd64)  ARCH_NAME="x64" ;;
+  *) echo "error: unsupported architecture: $ARCH" >&2; exit 1 ;;
+esac
+
+TARGET="${PLATFORM}-${ARCH_NAME}"
+NATIVE_BIN="${SCRIPT_DIR}/dist/${TARGET}/usecomputer"
+
+if [ "$PLATFORM" = "win32" ]; then
+  NATIVE_BIN="${NATIVE_BIN}.exe"
+fi
+
+if [ ! -x "$NATIVE_BIN" ]; then
+  echo "error: native binary not found at ${NATIVE_BIN}" >&2
+  echo "hint: run 'zig build' or install from npm to get prebuilt binaries" >&2
+  exit 1
+fi
+
+exec "$NATIVE_BIN" "$@"

package/build.zig

@@ -139,4 +139,16 @@ pub fn build(b: *std.Build) void {
     linkPlatformDeps(test_exe.root_module, target_os);
     const run_test = b.addRunArtifact(test_exe);
     test_step.dependOn(&run_test.step);
+
+    // Kitty graphics protocol tests
+    const kitty_test_mod = b.createModule(.{
+        .root_source_file = b.path("zig/src/kitty-graphics.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+    const kitty_test_exe = b.addTest(.{
+        .root_module = kitty_test_mod,
+    });
+    const run_kitty_test = b.addRunArtifact(kitty_test_exe);
+    test_step.dependOn(&run_kitty_test.step);
 }

package/dist/index.d.ts

@@ -1,7 +1,5 @@
-export { createCli } from './cli.js';
 export { createBridge, createBridgeFromNative } from './bridge.js';
 export * from './lib.js';
 export * from './coord-map.js';
 export * from './types.js';
-export * from './command-parsers.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAClE,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA;AAC1B,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAClE,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -1,7 +1,5 @@
-// Public API exports for usecomputer library helpers, parser, bridge, and CLI modules.
-export { createCli } from './cli.js';
+// Public API exports for usecomputer library helpers, bridge, and coord-map modules.
 export { createBridge, createBridgeFromNative } from './bridge.js';
 export * from './lib.js';
 export * from './coord-map.js';
 export * from './types.js';
-export * from './command-parsers.js';

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "usecomputer",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "Fast computer automation CLI for AI agents. Control any desktop with accessibility snapshots, clicks, typing, scrolling, and more.",
-  "bin": "./bin.js",
+  "bin": "./bin.sh",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -35,20 +35,10 @@
     "zig",
     "build.zig",
     "build.zig.zon",
-    "bin.js",
+    "bin.sh",
     "README.md",
     "CHANGELOG.md"
   ],
-  "scripts": {
-    "build": "tsc && chmod +x bin.js",
-    "build:zig": "zig build",
-    "build:native": "tsx scripts/build.ts",
-    "build:native:macos": "tsx scripts/build.ts darwin-arm64 darwin-x64",
-    "vm": "tsx scripts/vm.ts",
-    "test": "vitest --run",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "[ -n \"$CI\" ] || (pnpm build && pnpm build:native:macos)"
-  },
   "keywords": [
     "computer-use",
     "automation",
@@ -65,21 +55,17 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/remorses/kimaki.git",
-    "directory": "usecomputer"
+    "url": "git+https://github.com/remorses/usecomputer.git"
   },
-  "homepage": "https://github.com/remorses/kimaki/tree/main/usecomputer",
+  "homepage": "https://github.com/remorses/usecomputer",
   "bugs": {
-    "url": "https://github.com/remorses/kimaki/issues"
+    "url": "https://github.com/remorses/usecomputer/issues"
   },
   "os": [
     "darwin",
     "linux"
   ],
   "dependencies": {
-    "goke": "^6.3.0",
-    "picocolors": "^1.1.1",
-    "string-dedent": "^3.0.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {
@@ -88,7 +74,13 @@
     "typescript": "^5.8.3",
     "vitest": "^4.0.18"
   },
-  "optionalDependencies": {
-    "sharp": "^0.34.5"
+  "scripts": {
+    "build": "tsc && chmod +x bin.sh",
+    "build:zig": "zig build",
+    "build:native": "tsx scripts/build.ts",
+    "build:native:macos": "tsx scripts/build.ts darwin-arm64 darwin-x64",
+    "vm": "tsx scripts/vm.ts",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/src/index.ts

@@ -1,8 +1,6 @@
-// Public API exports for usecomputer library helpers, parser, bridge, and CLI modules.
+// Public API exports for usecomputer library helpers, bridge, and coord-map modules.
 
-export { createCli } from './cli.js'
 export { createBridge, createBridgeFromNative } from './bridge.js'
 export * from './lib.js'
 export * from './coord-map.js'
 export * from './types.js'
-export * from './command-parsers.js'

package/zig/src/kitty-graphics.zig

@@ -0,0 +1,151 @@
+// Kitty Graphics Protocol emission for usecomputer screenshot output.
+//
+// When AGENT_GRAPHICS=kitty is set in the environment, CLI tools can emit
+// images inline to stdout via APC escape sequences. An agent plugin
+// (like kitty-graphics-agent) intercepts these sequences, strips them from
+// the text output, and injects the images as LLM-visible attachments.
+//
+// Protocol format:
+//   \x1b_G<control_data>;<base64_payload>\x1b\\
+//
+// Large images are chunked: continuation chunks use m=1, the last chunk
+// uses m=0. Chunk size is 4096 bytes of base64 data (per spec convention).
+//
+// Reference: https://sw.kovidgoyal.net/kitty/graphics-protocol/
+// Agent spec: https://github.com/remorses/kitty-graphics-agent
+
+const std = @import("std");
+
+const base64_alphabet: [64]u8 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/".*;
+const base64_encoder = std.base64.Base64Encoder.init(base64_alphabet, '=');
+
+/// Max base64 characters per kitty graphics chunk (spec convention).
+const chunk_size: usize = 4096;
+
+/// Check whether a value string contains "kitty".
+/// Extracted for deterministic testing without env var manipulation.
+pub fn containsKitty(val: []const u8) bool {
+    return std.mem.indexOf(u8, val, "kitty") != null;
+}
+
+/// Check whether the AGENT_GRAPHICS environment variable contains "kitty".
+/// CLIs should call this to decide whether to emit kitty graphics on stdout.
+/// Uses std.process.getEnvVarOwned for cross-platform compatibility (works on
+/// macOS, Linux, and Windows — std.posix.getenv is unavailable on Windows).
+pub fn canEmitAgentGraphics() bool {
+    const alloc = std.heap.page_allocator;
+    const val = std.process.getEnvVarOwned(alloc, "AGENT_GRAPHICS") catch return false;
+    defer alloc.free(val);
+    return containsKitty(val);
+}
+
+/// Emit a PNG image as Kitty Graphics Protocol escape sequences.
+///
+/// Writes APC sequences to `writer` with f=100 (PNG), a=T (transmit+display),
+/// and chunked transfer (m=1 for continuation, m=0 for last/only chunk).
+///
+/// `png_data` is the raw PNG file bytes (not base64-encoded).
+pub fn emitKittyGraphics(png_data: []const u8, writer: anytype) !void {
+    // Base64-encode the entire PNG
+    const encoded_len = base64_encoder.calcSize(png_data.len);
+
+    // Allocate buffer for full base64 string
+    const encoded_buf = try std.heap.page_allocator.alloc(u8, encoded_len);
+    defer std.heap.page_allocator.free(encoded_buf);
+
+    const encoded = base64_encoder.encode(encoded_buf, png_data);
+
+    // Emit chunks
+    var offset: usize = 0;
+    while (offset < encoded.len) {
+        const remaining = encoded.len - offset;
+        const this_chunk_size = @min(remaining, chunk_size);
+        const is_last = (offset + this_chunk_size >= encoded.len);
+        const chunk = encoded[offset .. offset + this_chunk_size];
+
+        if (offset == 0) {
+            // First (or only) chunk: include full control data
+            if (is_last) {
+                try writer.print("\x1b_Gf=100,a=T,m=0;{s}\x1b\\", .{chunk});
+            } else {
+                try writer.print("\x1b_Gf=100,a=T,m=1;{s}\x1b\\", .{chunk});
+            }
+        } else {
+            // Continuation chunk: only m= key (per spec)
+            if (is_last) {
+                try writer.print("\x1b_Gm=0;{s}\x1b\\", .{chunk});
+            } else {
+                try writer.print("\x1b_Gm=1;{s}\x1b\\", .{chunk});
+            }
+        }
+
+        offset += this_chunk_size;
+    }
+}
+
+// ─── Tests ───
+
+test "containsKitty detects kitty in value" {
+    try std.testing.expect(containsKitty("kitty"));
+    try std.testing.expect(containsKitty("kitty,iterm2"));
+    try std.testing.expect(containsKitty("iterm2,kitty"));
+    try std.testing.expect(!containsKitty("iterm2"));
+    try std.testing.expect(!containsKitty(""));
+    try std.testing.expect(!containsKitty("KITTY")); // case-sensitive per spec
+}
+
+test "emitKittyGraphics single chunk for small image" {
+    var buf = std.ArrayList(u8).initCapacity(std.testing.allocator, 0) catch unreachable;
+    defer buf.deinit(std.testing.allocator);
+
+    // Small PNG-like data (just bytes, doesn't need to be valid PNG for emission test)
+    const small_data = "tiny-png-data";
+    try emitKittyGraphics(small_data, buf.writer(std.testing.allocator));
+
+    const output = buf.items;
+    // Should start with APC start
+    try std.testing.expect(std.mem.startsWith(u8, output, "\x1b_G"));
+    // Should have f=100,a=T,m=0 (single chunk = last chunk)
+    try std.testing.expect(std.mem.indexOf(u8, output, "f=100,a=T,m=0;") != null);
+    // Should end with ST
+    try std.testing.expect(std.mem.endsWith(u8, output, "\x1b\\"));
+}
+
+test "emitKittyGraphics multi chunk for large data" {
+    var buf = std.ArrayList(u8).initCapacity(std.testing.allocator, 0) catch unreachable;
+    defer buf.deinit(std.testing.allocator);
+
+    // Create data large enough to require multiple chunks after base64 encoding.
+    // 4096 base64 chars ~ 3072 raw bytes. Use 8000 raw bytes to get ~10668 base64 chars = 3 chunks.
+    var large_data: [8000]u8 = undefined;
+    for (&large_data) |*b| {
+        b.* = 0xAB;
+    }
+    try emitKittyGraphics(&large_data, buf.writer(std.testing.allocator));
+
+    const output = buf.items;
+    // First chunk should have f=100,a=T,m=1
+    try std.testing.expect(std.mem.indexOf(u8, output, "f=100,a=T,m=1;") != null);
+    // Last chunk should have m=0
+    // Find the last occurrence of m=0
+    var found_m0 = false;
+    var search_pos: usize = 0;
+    while (std.mem.indexOfPos(u8, output, search_pos, "m=0;")) |pos| {
+        found_m0 = true;
+        search_pos = pos + 1;
+    }
+    try std.testing.expect(found_m0);
+    // Continuation chunks should have m=1 (without f=100,a=T prefix)
+    // Count occurrences of \x1b_Gm=1; (continuation, no control data beyond m=)
+    var continuation_count: usize = 0;
+    var cpos: usize = 0;
+    while (std.mem.indexOfPos(u8, output, cpos, "\x1b_Gm=1;")) |pos| {
+        continuation_count += 1;
+        cpos = pos + 1;
+    }
+    // With ~10668 base64 chars / 4096 chunk size = 3 chunks total
+    // First chunk: \x1b_Gf=100,a=T,m=1; (1 occurrence)
+    // Middle chunk(s): \x1b_Gm=1; (at least 1)
+    // Last chunk: \x1b_Gm=0;
+    try std.testing.expect(continuation_count >= 1);
+}

package/zig/src/lib.zig

@@ -2020,6 +2020,127 @@ fn writeScreenshotPng(input: struct {
     }
 }
 
+/// Draw a red crosshair+circle debug marker on an existing PNG file (macOS only).
+/// Reads the PNG, draws the marker at (x, y) in image coordinates, writes back.
+pub fn drawMarkerOnPng(input: struct {
+    path: []const u8,
+    x: f64,
+    y: f64,
+    imageWidth: f64,
+    imageHeight: f64,
+}) CommandResult {
+    if (builtin.target.os.tag != .macos) {
+        return failCommand("drawMarkerOnPng", "UNSUPPORTED_PLATFORM", "debug-point image overlay is only supported on macOS");
+    }
+
+    // Load the existing PNG
+    const path_as_u8: [*]const u8 = @ptrCast(input.path.ptr);
+    const file_url = c.CFURLCreateFromFileSystemRepresentation(
+        null,
+        path_as_u8,
+        @as(c_long, @intCast(input.path.len)),
+        0,
+    );
+    if (file_url == null) return failCommand("drawMarkerOnPng", "LOAD_FAILED", "failed to create file URL");
+    defer c.CFRelease(file_url);
+
+    const source = c.CGImageSourceCreateWithURL(file_url, null);
+    if (source == null) return failCommand("drawMarkerOnPng", "LOAD_FAILED", "failed to load PNG");
+    defer c.CFRelease(source);
+
+    const image = c.CGImageSourceCreateImageAtIndex(source, 0, null);
+    if (image == null) return failCommand("drawMarkerOnPng", "LOAD_FAILED", "failed to decode PNG image");
+    defer c.CFRelease(image);
+
+    const w = c.CGImageGetWidth(image);
+    const h = c.CGImageGetHeight(image);
+
+    // Create bitmap context
+    const color_space = c.CGColorSpaceCreateDeviceRGB();
+    if (color_space == null) return failCommand("drawMarkerOnPng", "DRAW_FAILED", "failed to create color space");
+    defer c.CFRelease(color_space);
+
+    const ctx = c.CGBitmapContextCreate(
+        null,
+        w,
+        h,
+        8,
+        0,
+        color_space,
+        c.kCGImageAlphaPremultipliedLast,
+    );
+    if (ctx == null) return failCommand("drawMarkerOnPng", "DRAW_FAILED", "failed to create bitmap context");
+    defer c.CFRelease(ctx);
+
+    // Draw original image
+    const img_rect: c.CGRect = .{
+        .origin = .{ .x = 0, .y = 0 },
+        .size = .{ .width = @floatFromInt(w), .height = @floatFromInt(h) },
+    };
+    c.CGContextDrawImage(ctx, img_rect, image);
+
+    // Flip Y: CGContext origin is bottom-left, marker coords are top-left
+    const px = input.x;
+    const py = @as(f64, @floatFromInt(h)) - input.y;
+
+    const pi = std.math.pi;
+
+    // White crosshair (background for contrast)
+    c.CGContextSetRGBStrokeColor(ctx, 1, 1, 1, 0.95);
+    c.CGContextSetLineWidth(ctx, 5);
+    c.CGContextSetLineCap(ctx, 1); // kCGLineCapRound
+    c.CGContextMoveToPoint(ctx, px - 22, py);
+    c.CGContextAddLineToPoint(ctx, px + 22, py);
+    c.CGContextStrokePath(ctx);
+    c.CGContextMoveToPoint(ctx, px, py - 22);
+    c.CGContextAddLineToPoint(ctx, px, py + 22);
+    c.CGContextStrokePath(ctx);
+
+    // White ring
+    c.CGContextSetLineWidth(ctx, 4);
+    c.CGContextAddArc(ctx, px, py, 18, 0, 2 * pi, 0);
+    c.CGContextStrokePath(ctx);
+
+    // Red crosshair
+    c.CGContextSetRGBStrokeColor(ctx, 1, 0.176, 0.176, 1); // #ff2d2d
+    c.CGContextSetLineWidth(ctx, 3);
+    c.CGContextSetLineCap(ctx, 1);
+    c.CGContextMoveToPoint(ctx, px - 22, py);
+    c.CGContextAddLineToPoint(ctx, px + 22, py);
+    c.CGContextStrokePath(ctx);
+    c.CGContextMoveToPoint(ctx, px, py - 22);
+    c.CGContextAddLineToPoint(ctx, px, py + 22);
+    c.CGContextStrokePath(ctx);
+
+    // Red ring
+    c.CGContextSetLineWidth(ctx, 2);
+    c.CGContextAddArc(ctx, px, py, 18, 0, 2 * pi, 0);
+    c.CGContextStrokePath(ctx);
+
+    // Filled red center dot with white stroke
+    c.CGContextSetRGBFillColor(ctx, 1, 0.176, 0.176, 1);
+    c.CGContextAddArc(ctx, px, py, 10, 0, 2 * pi, 0);
+    c.CGContextFillPath(ctx);
+    c.CGContextSetRGBStrokeColor(ctx, 1, 1, 1, 1);
+    c.CGContextSetLineWidth(ctx, 3);
+    c.CGContextAddArc(ctx, px, py, 10, 0, 2 * pi, 0);
+    c.CGContextStrokePath(ctx);
+
+    // Get result image and write back
+    const result_image = c.CGBitmapContextCreateImage(ctx);
+    if (result_image == null) return failCommand("drawMarkerOnPng", "DRAW_FAILED", "failed to create result image");
+    defer c.CFRelease(result_image);
+
+    writeScreenshotPng(.{
+        .image = result_image,
+        .output_path = input.path,
+    }) catch {
+        return failCommand("drawMarkerOnPng", "WRITE_FAILED", "failed to write annotated PNG");
+    };
+
+    return okCommand();
+}
+
 fn resolveMouseButton(button: []const u8) !MouseButtonKind {
     if (std.ascii.eqlIgnoreCase(button, "left")) {
         return .left;