feat(snapshot): Render user-defined context

Render snapshot image sidecar context recursively as Markdown bullets under a Context section. Preserve supported scalar values and nested objects while skipping unsupported or empty values.

Co-Authored-By: Codex CLI <noreply@openai.com>

Author: cameroncooke

packages/mcp-core/src/tools/get-snapshot-details.test.ts

@@ -121,6 +121,8 @@ const snapshotFixture = {
   unchanged: [],
 };
 
+const LONG_CONTEXT_VALUE = "x".repeat(220);
+
 const headImageInfo = {
   content_hash: "abc123",
   display_name: "login_screen.png",
@@ -132,11 +134,35 @@ const headImageInfo = {
   image_url:
     "/api/0/organizations/sentry/preprodartifacts/snapshots/231949/images/auth_login_screen.png/download/",
   context: {
+    empty_object: {},
+    empty_string: "",
+    metadata: {
+      enabled: true,
+      metrics: {
+        attempts: 2,
+        ratio: 0.25,
+      },
+      unsupported_array: ["hidden"],
+      unsupported_null: null,
+    },
+    deep: {
+      level1: {
+        level2: {
+          level3: {
+            level4: {
+              level5: "visible",
+            },
+          },
+        },
+      },
+    },
+    long_value: LONG_CONTEXT_VALUE,
     preview: {
       container_display_name: "Auth Login",
       display_name: "login_screen.png",
     },
     simulator: { device_name: "iPhone 16" },
+    test_name: "LoginUITests.testLoginScreen",
   },
 };
 
@@ -621,8 +647,28 @@ describe("get_snapshot_details", () => {
     expect(textParts[0]!.text).toContain("**Diff**: 12.5%");
     expect(textParts[0]!.text).toContain("**Group**: auth");
     expect(textParts[0]!.text).toContain("1080×1920");
-    expect(textParts[0]!.text).toContain("**Container**: Auth Login");
-    expect(textParts[0]!.text).toContain("**Device**: iPhone 16");
+    expect(textParts[0]!.text).toContain("### Context");
+    expect(textParts[0]!.text).toContain(
+      "- **metadata**:\n  - **enabled**: true\n  - **metrics**:\n    - **attempts**: 2\n    - **ratio**: 0.25",
+    );
+    expect(textParts[0]!.text).toContain("          - **level5**: visible");
+    expect(textParts[0]!.text).toContain(
+      `- **long_value**: ${LONG_CONTEXT_VALUE}`,
+    );
+    expect(textParts[0]!.text).not.toContain("more context lines omitted");
+    expect(textParts[0]!.text).toContain(
+      "- **preview**:\n  - **container_display_name**: Auth Login\n  - **display_name**: login_screen.png",
+    );
+    expect(textParts[0]!.text).toContain(
+      "- **simulator**:\n  - **device_name**: iPhone 16",
+    );
+    expect(textParts[0]!.text).toContain(
+      "- **test_name**: LoginUITests.testLoginScreen",
+    );
+    expect(textParts[0]!.text).not.toContain("empty_object");
+    expect(textParts[0]!.text).not.toContain("empty_string");
+    expect(textParts[0]!.text).not.toContain("unsupported_array");
+    expect(textParts[0]!.text).not.toContain("unsupported_null");
     expect(imageParts.length).toBe(3);
     expect(imageParts[0]!.mimeType).toBe("image/png");
     expect(imageParts[1]!.mimeType).toBe("image/jpeg");

packages/mcp-core/src/tools/get-snapshot-details.ts

@@ -14,6 +14,7 @@ import { blobToBase64 } from "../internal/blob-utils";
 import {
   formatSnapshotDiffPercent,
   getSnapshotImageDisplayName,
+  renderSnapshotImageContext,
   renderSnapshotImageTreeSection,
   type SnapshotImageEntry,
   type SnapshotImageTreeItem,
@@ -25,12 +26,6 @@ interface SnapshotDiffPair {
   diff?: number | null;
 }
 
-interface SnapshotImageContext {
-  preview?: { container_display_name?: string; display_name?: string };
-  simulator?: { device_name?: string };
-  test_name?: string;
-}
-
 interface SnapshotImageInfo {
   content_hash?: string;
   display_name?: string | null;
@@ -40,7 +35,7 @@ interface SnapshotImageInfo {
   height?: number;
   description?: string | null;
   image_url?: string;
-  context?: SnapshotImageContext;
+  context?: unknown;
   [key: string]: unknown;
 }
 
@@ -173,14 +168,10 @@ function formatImageMetadata(img: SnapshotImageInfo): string[] {
   if (img.width || img.height)
     lines.push(`- **Dimensions**: ${img.width}×${img.height}`);
   if (img.description) lines.push(`- **Description**: ${img.description}`);
-  if (img.context?.preview?.container_display_name)
-    lines.push(
-      `- **Container**: ${img.context.preview.container_display_name}`,
-    );
-  if (img.context?.simulator?.device_name)
-    lines.push(`- **Device**: ${img.context.simulator.device_name}`);
-  if (img.context?.test_name)
-    lines.push(`- **Test**: ${img.context.test_name}`);
+  const contextLines = renderSnapshotImageContext(img.context);
+  if (contextLines.length > 0) {
+    lines.push("", "### Context", ...contextLines);
+  }
   return lines;
 }
 

packages/mcp-core/src/tools/snapshot-formatting.ts

@@ -53,6 +53,19 @@ export function renderSnapshotImageTreeSection(
   return lines;
 }
 
+export function renderSnapshotImageContext(context: unknown): string[] {
+  if (!isPlainObject(context)) {
+    return [];
+  }
+
+  const contextLines = renderContextObject(context, 0);
+  if (contextLines.length === 0) {
+    return [];
+  }
+
+  return contextLines;
+}
+
 function createBranch(label: string): TreeBranch {
   return { kind: "branch", label, children: new Map(), leaves: [] };
 }
@@ -129,3 +142,49 @@ function renderEntry(
   }
   return lines.join("\n");
 }
+
+function renderContextObject(
+  context: Record<string, unknown>,
+  depth: number,
+): string[] {
+  const prefix = "  ".repeat(depth);
+  return Object.entries(context).flatMap(([key, value]) => {
+    const formatted = formatSupportedContextValue(value);
+    if (formatted !== null) {
+      return [`${prefix}- **${key}**: ${formatted}`];
+    }
+
+    if (!isPlainObject(value)) {
+      return [];
+    }
+
+    const children = renderContextObject(value, depth + 1);
+    return children.length > 0 ? [`${prefix}- **${key}**:`, ...children] : [];
+  });
+}
+
+function formatSupportedContextValue(value: unknown): string | null {
+  if (typeof value === "string") {
+    const normalized = value.trim().replace(/\s+/g, " ");
+    return normalized.length > 0 ? normalized : null;
+  }
+
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? String(value) : null;
+  }
+
+  if (typeof value === "boolean") {
+    return String(value);
+  }
+
+  return null;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== "object") {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}