@stigmer/react 3.9.0 → 3.10.0

package/src/execution/MessageThread.tsx

@@ -22,6 +22,7 @@ import { displayFileChangeSets } from "@stigmer/sdk";
 import { cn } from "@stigmer/theme";
 import { isTerminalPhase } from "./execution-phases.js";
 import { MessageEntry, type MessageEntryProps } from "./MessageEntry.js";
+import type { MessageAttachmentView } from "./MessageAttachments.js";
 import { ToolCallGroup } from "./ToolCallGroup.js";
 import { SubAgentSection } from "./SubAgentSection.js";
 import { ExecutionPhaseBadge } from "./ExecutionPhaseBadge.js";
@@ -124,6 +125,16 @@ export interface MessageThreadProps {
    * first snapshot.
    */
   readonly pendingUserMessage?: string | null;
+  /**
+   * Attachments submitted with the pending user message, rendered as chips
+   * on the optimistic bubble so the files never vanish between submit and
+   * the stream's first snapshot (stigmer/stigmer#372). Supply
+   * {@link useSessionConversation}'s `pendingAttachments`; clear together
+   * with {@link pendingUserMessage}. Chips are inert on the pending bubble
+   * (no execution record yet); previews and downloads light up the moment
+   * the real turn replaces it.
+   */
+  readonly pendingAttachments?: readonly MessageAttachmentView[] | null;
   /**
    * Marks the pending user message as failed-to-send. The optimistic
    * bubble renders an inline "Couldn't send — Retry" affordance instead
@@ -339,7 +350,7 @@ export function threadContentColumnClass(
  * part of the public API.
  */
 export type ThreadItem =
-  | { readonly kind: "message"; readonly message: AgentMessage; readonly key: string; readonly isPending?: boolean; readonly isFailed?: boolean; readonly isEditable?: boolean; readonly isPlanDocument?: boolean; readonly interactionMode?: InteractionMode }
+  | { readonly kind: "message"; readonly message: AgentMessage; readonly key: string; readonly isPending?: boolean; readonly isFailed?: boolean; readonly isEditable?: boolean; readonly isPlanDocument?: boolean; readonly interactionMode?: InteractionMode; readonly attachments?: readonly MessageAttachmentView[]; readonly executionId?: string }
   | { readonly kind: "tool-group"; readonly toolCalls: readonly ToolCall[]; readonly subAgentExecutions: readonly SubAgentExecution[]; readonly key: string }
   | { readonly kind: "sub-agent"; readonly subAgentExecution: SubAgentExecution; readonly key: string }
   | { readonly kind: "phase-badge"; readonly phase: ExecutionPhase; readonly key: string }
@@ -557,6 +568,7 @@ export function buildThreadItems(
   editableActiveTurn = false,
   includeFileReviewRecords = false,
   collapseStreamingPlan = false,
+  pendingAttachments?: readonly MessageAttachmentView[] | null,
 ): ThreadItem[] {
   const items: ThreadItem[] = [];
   // Tool-call ids that render as an inline-approval-capable ToolCallItem (a
@@ -717,6 +729,12 @@ export function buildThreadItems(
         pendingUserMessage != null &&
         specMessage === pendingUserMessage;
 
+      // The turn's submitted files (spec.attachments, by reference — the spec
+      // never mutates and structural sharing keeps the ref stable, so the
+      // memoized bubble skips re-renders). The execution id rides along for
+      // the presigned-URL affordances; the `_e${ei}` synthetic fallback is
+      // display-only and must never be presigned against.
+      const specAttachments = exec.spec?.attachments;
       items.push({
         kind: "message",
         message: syntheticHumanMsg,
@@ -727,6 +745,11 @@ export function buildThreadItems(
         // The turn's mode marks the prompt bubble (a "Plan" pill on Plan
         // turns) so the transcript reads unambiguously after mode switches.
         interactionMode: exec.spec?.executionConfig?.interactionMode,
+        attachments:
+          specAttachments && specAttachments.length > 0
+            ? specAttachments
+            : undefined,
+        executionId: exec.metadata?.id,
       });
     }
 
@@ -1023,6 +1046,14 @@ export function buildThreadItems(
         // sending state — the two are mutually exclusive.
         isPending: !pendingMessageFailed,
         isFailed: pendingMessageFailed,
+        // The submit context's attachments: evidence the files rode with the
+        // turn, kept on failure so retry shows what will be re-sent. No
+        // executionId yet — chips render inert until the real turn (same
+        // bridge key) replaces this bubble and brings the presign seam.
+        attachments:
+          pendingAttachments && pendingAttachments.length > 0
+            ? pendingAttachments
+            : undefined,
       });
     }
   }
@@ -1057,6 +1088,7 @@ export function MessageThread({
   executions,
   activeStreamExecution,
   pendingUserMessage,
+  pendingAttachments,
   pendingMessageFailed = false,
   onRetrySend,
   onRetryExecution,
@@ -1089,8 +1121,8 @@ export function MessageThread({
   // the plan streaming inline, where it remains readable (DD-011).
   const collapseStreamingPlan = onOpenPlan != null;
   const items = useMemo(
-    () => buildThreadItems(executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents, pendingMessageFailed, editableActiveTurn, showFileReviewRecords, collapseStreamingPlan),
-    [executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents, pendingMessageFailed, editableActiveTurn, showFileReviewRecords, collapseStreamingPlan],
+    () => buildThreadItems(executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents, pendingMessageFailed, editableActiveTurn, showFileReviewRecords, collapseStreamingPlan, pendingAttachments),
+    [executions, activeStreamExecution, pendingUserMessage, includeApprovals, workspaceEntries, summarizationEvents, pendingMessageFailed, editableActiveTurn, showFileReviewRecords, collapseStreamingPlan, pendingAttachments],
   );
 
   useKeyStability(items);
@@ -1413,6 +1445,7 @@ export function ThreadItemRenderer({
         return (
           <FailedUserMessage
             message={item.message}
+            attachments={item.attachments}
             onRetry={onRetrySend}
             MessageEntryComponent={Entry}
           />
@@ -1424,6 +1457,8 @@ export function ThreadItemRenderer({
           className={item.isPending ? "opacity-70" : undefined}
           isPlanDocument={item.isPlanDocument}
           interactionMode={item.interactionMode}
+          attachments={item.attachments}
+          executionId={item.executionId}
           onEdit={
             item.isEditable && onEditMessage
               ? () => onEditMessage(item.message.content)
@@ -1555,16 +1590,21 @@ export function ThreadItemRenderer({
  */
 function FailedUserMessage({
   message,
+  attachments,
   onRetry,
   MessageEntryComponent,
 }: {
   message: AgentMessage;
+  attachments?: readonly MessageAttachmentView[];
   onRetry?: () => void;
   MessageEntryComponent: ComponentType<MessageEntryProps>;
 }) {
   return (
     <div className="flex flex-col gap-1">
-      <MessageEntryComponent message={message} />
+      {/* Attachments stay visible on the failed bubble — the one turn where
+          the user most needs evidence of what they tried to send (and what
+          Retry will re-send). No executionId: the send never created one. */}
+      <MessageEntryComponent message={message} attachments={attachments} />
       <div
         role="alert"
         className="mx-4 flex items-center gap-2 text-xs text-destructive"

package/src/execution/__tests__/MessageEntry-attachments.test.tsx

@@ -0,0 +1,228 @@
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { MessageType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { MessageEntry } from "../MessageEntry";
+import type { MessageAttachmentView } from "../MessageAttachments";
+
+// ---------------------------------------------------------------------------
+// MessageEntry attachment rendering (stigmer/stigmer#372): the human bubble
+// shows the turn's submitted files — image previews and document downloads
+// when the execution record exists, inert chips on the pending bubble, and
+// nothing at all when the turn had no attachments.
+//
+// The presign hooks are mocked at the module boundary: these are rendering
+// tests, and the URL-minting contract has its own coverage.
+// ---------------------------------------------------------------------------
+
+const downloadSpy = vi.fn(() => Promise.resolve());
+let urlState: { url: string | null; error: Error | null } = {
+  url: null,
+  error: null,
+};
+
+vi.mock("../useArtifactDownloadUrl", () => ({
+  useArtifactDownloadUrl: (executionId: string | null, storageKey: string | null) => ({
+    url: executionId && storageKey ? urlState.url : null,
+    isLoading: false,
+    isRefetching: false,
+    error: urlState.error,
+    refetch: vi.fn(),
+  }),
+}));
+
+vi.mock("../useArtifactDownload", () => ({
+  useArtifactDownload: (executionId: string | null) => ({
+    download: executionId ? downloadSpy : vi.fn(() => Promise.resolve()),
+    isDownloading: false,
+    error: null,
+  }),
+}));
+
+// happy-dom does not implement the native dialog show/close methods.
+beforeAll(() => {
+  HTMLDialogElement.prototype.showModal = function showModal() {
+    this.open = true;
+  };
+  HTMLDialogElement.prototype.close = function close() {
+    this.open = false;
+  };
+});
+
+afterEach(() => {
+  cleanup();
+  downloadSpy.mockClear();
+  urlState = { url: null, error: null };
+});
+
+function humanMessage(content: string) {
+  const msg = create(AgentMessageSchema);
+  msg.type = MessageType.MESSAGE_HUMAN;
+  msg.content = content;
+  return msg;
+}
+
+const imageAttachment: MessageAttachmentView = {
+  filename: "screenshot.png",
+  contentType: "image/png",
+  storageKey: "attachments/01AAA/screenshot.png",
+};
+
+const documentAttachment: MessageAttachmentView = {
+  filename: "notes.txt",
+  contentType: "text/plain",
+  storageKey: "attachments/01BBB/notes.txt",
+};
+
+describe("MessageEntry attachment rendering", () => {
+  it("renders no attachment row when the turn has none", () => {
+    render(<MessageEntry message={humanMessage("Just text.")} />);
+
+    expect(screen.queryByRole("list", { name: "Submitted attachments" })).toBeNull();
+    expect(screen.getByText("Just text.")).toBeTruthy();
+  });
+
+  it("renders an image preview chip with the presigned URL and click-to-open lightbox", () => {
+    urlState = { url: "https://r2.example/presigned/screenshot", error: null };
+
+    const { container } = render(
+      <MessageEntry
+        message={humanMessage("See the screenshot.")}
+        attachments={[imageAttachment]}
+        executionId="exec-1"
+      />,
+    );
+
+    expect(screen.getByRole("list", { name: "Submitted attachments" })).toBeTruthy();
+    const img = container.querySelector("img[aria-hidden='true']");
+    expect(img?.getAttribute("src")).toBe("https://r2.example/presigned/screenshot");
+
+    // Click-to-open: the shared lightbox mounts with the full image.
+    fireEvent.click(screen.getByRole("button", { name: "Preview screenshot.png" }));
+    const dialog = container.querySelector("dialog");
+    expect(dialog).toBeTruthy();
+    expect(dialog!.getAttribute("aria-label")).toBe("Preview screenshot.png");
+  });
+
+  it("renders a document chip that downloads under the original filename", () => {
+    render(
+      <MessageEntry
+        message={humanMessage("The notes are attached.")}
+        attachments={[documentAttachment]}
+        executionId="exec-1"
+      />,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Download notes.txt" }));
+    expect(downloadSpy).toHaveBeenCalledWith(
+      "attachments/01BBB/notes.txt",
+      "notes.txt",
+    );
+  });
+
+  it("renders no visible filename on image tiles — identity lives in the tooltip and accessible label", () => {
+    urlState = { url: "https://r2.example/presigned/screenshot", error: null };
+
+    render(
+      <MessageEntry
+        message={humanMessage("See the screenshot.")}
+        attachments={[imageAttachment]}
+        executionId="exec-1"
+      />,
+    );
+
+    // The tile is preview-only: no "screenshot.png" text node anywhere…
+    expect(screen.queryByText("screenshot.png")).toBeNull();
+    // …but the name stays reachable — tooltip on the listitem, aria on both.
+    const tile = screen.getByRole("listitem", { name: "screenshot.png" });
+    expect(tile.getAttribute("title")).toBe("screenshot.png");
+    expect(
+      screen.getByRole("button", { name: "Preview screenshot.png" }),
+    ).toBeTruthy();
+  });
+
+  it("pulses the image tile only while the presigned URL is being minted", () => {
+    urlState = { url: null, error: null };
+
+    const { container } = render(
+      <MessageEntry
+        message={humanMessage("See the screenshot.")}
+        attachments={[imageAttachment]}
+        executionId="exec-1"
+      />,
+    );
+
+    // Mint in flight: pulse placeholder, no image yet.
+    expect(container.querySelector(".animate-pulse")).toBeTruthy();
+    expect(container.querySelector("img")).toBeNull();
+  });
+
+  it("renders inert chips on the pending bubble (no executionId): no preview, no download", () => {
+    const { container } = render(
+      <MessageEntry
+        message={humanMessage("Sending files…")}
+        attachments={[imageAttachment, documentAttachment]}
+      />,
+    );
+
+    // Both files are present as evidence — the image as a glyph tile
+    // (named via aria/tooltip), the document as a filename chip…
+    expect(screen.getByRole("list", { name: "Submitted attachments" })).toBeTruthy();
+    expect(screen.getByRole("listitem", { name: "screenshot.png" })).toBeTruthy();
+    expect(screen.getByText("notes.txt")).toBeTruthy();
+    // …but no byte-backed affordances exist yet.
+    expect(container.querySelector("img")).toBeNull();
+    expect(screen.queryByRole("button", { name: /Preview|Download/ })).toBeNull();
+    // The tile is STATIC — a pulse would promise bytes that a failed send
+    // (the other no-executionId bubble) never delivers.
+    expect(container.querySelector(".animate-pulse")).toBeNull();
+  });
+
+  it("degrades an image chip to the document treatment when the URL cannot be minted", () => {
+    urlState = { url: null, error: new Error("presign failed") };
+
+    const { container } = render(
+      <MessageEntry
+        message={humanMessage("See the screenshot.")}
+        attachments={[imageAttachment]}
+        executionId="exec-1"
+      />,
+    );
+
+    // Never a broken-image glyph — the file stays reachable via download.
+    expect(container.querySelector("img")).toBeNull();
+    expect(
+      screen.getByRole("button", { name: "Download screenshot.png" }),
+    ).toBeTruthy();
+  });
+
+  it("falls back to the storage key's basename when the filename is missing", () => {
+    render(
+      <MessageEntry
+        message={humanMessage("Unnamed attachment.")}
+        attachments={[{ storageKey: "attachments/01CCC/data.bin" }]}
+        executionId="exec-1"
+      />,
+    );
+
+    expect(screen.getByText("data.bin")).toBeTruthy();
+  });
+
+  it("ignores attachments on non-human messages", () => {
+    const aiMsg = create(AgentMessageSchema);
+    aiMsg.type = MessageType.MESSAGE_AI;
+    aiMsg.content = "Assistant reply.";
+
+    render(
+      <MessageEntry
+        message={aiMsg}
+        attachments={[documentAttachment]}
+        executionId="exec-1"
+      />,
+    );
+
+    expect(screen.queryByRole("list", { name: "Submitted attachments" })).toBeNull();
+  });
+});

package/src/execution/__tests__/buildThreadItems-attachments.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  AgentExecutionSpecSchema,
+  AttachmentSchema,
+  type Attachment,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { buildThreadItems, type ThreadItem } from "../MessageThread";
+
+// ---------------------------------------------------------------------------
+// buildThreadItems attachment stamping (stigmer/stigmer#372)
+//
+// The human turn's submitted files come from two sources: the execution
+// record's spec.attachments (durable, presign-capable) and the submit
+// context's pendingAttachments (optimistic bubble, no execution yet). These
+// tests pin both stamps, the empty-list omission, and the reference
+// stability the memoized bubble depends on.
+// ---------------------------------------------------------------------------
+
+function makeAttachment(filename: string, storageKey: string): Attachment {
+  return create(AttachmentSchema, {
+    filename,
+    storageKey,
+    contentType: filename.endsWith(".png") ? "image/png" : "text/plain",
+  });
+}
+
+function makeExecution(opts: {
+  id: string;
+  specMessage: string;
+  attachments?: Attachment[];
+}): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  exec.metadata = create(ApiResourceMetadataSchema, { id: opts.id });
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = opts.specMessage;
+  if (opts.attachments) spec.attachments = opts.attachments;
+  exec.spec = spec;
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = ExecutionPhase.EXECUTION_COMPLETED;
+  exec.status = status;
+  return exec;
+}
+
+function promptItem(items: readonly ThreadItem[], execId: string) {
+  return items.find(
+    (i): i is Extract<ThreadItem, { kind: "message" }> =>
+      i.kind === "message" && i.key === `${execId}-spec`,
+  );
+}
+
+function pendingItem(items: readonly ThreadItem[]) {
+  return items.find(
+    (i): i is Extract<ThreadItem, { kind: "message" }> =>
+      i.kind === "message" && i.key === "pending-user-turn",
+  );
+}
+
+describe("buildThreadItems spec.attachments stamping", () => {
+  it("stamps the synthetic human turn with the spec's attachments and the execution id", () => {
+    const attachments = [
+      makeAttachment("notes.png", "attachments/01AAA/notes.png"),
+      makeAttachment("report.txt", "attachments/01BBB/report.txt"),
+    ];
+    const exec = makeExecution({
+      id: "exec-attach",
+      specMessage: "Look at these files.",
+      attachments,
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    const prompt = promptItem(items, "exec-attach");
+
+    expect(prompt).toBeDefined();
+    expect(prompt!.executionId).toBe("exec-attach");
+    // Stamped BY REFERENCE: structural sharing keeps spec.attachments stable
+    // across streaming frames, so the memoized bubble must receive the same
+    // array object, not a copy (DD-010).
+    expect(prompt!.attachments).toBe(exec.spec!.attachments);
+    expect(prompt!.attachments).toHaveLength(2);
+  });
+
+  it("stamps NO attachments field when the spec has none (empty list omitted)", () => {
+    const exec = makeExecution({
+      id: "exec-plain",
+      specMessage: "Just text.",
+    });
+
+    const items = buildThreadItems([exec], null, null, false, undefined);
+    const prompt = promptItem(items, "exec-plain");
+
+    expect(prompt).toBeDefined();
+    expect(prompt!.attachments).toBeUndefined();
+    // The execution id still rides along — other affordances may need it.
+    expect(prompt!.executionId).toBe("exec-plain");
+  });
+});
+
+describe("buildThreadItems pendingAttachments stamping", () => {
+  const pendingAttachments = [
+    { filename: "sketch.png", contentType: "image/png", storageKey: "attachments/01CCC/sketch.png" },
+  ];
+
+  it("carries the submit context's attachments on the pending bubble, without an execution id", () => {
+    const items = buildThreadItems(
+      [],
+      null,
+      "Here is a sketch.",
+      false,
+      undefined,
+      undefined,
+      false,
+      false,
+      false,
+      false,
+      pendingAttachments,
+    );
+    const pending = pendingItem(items);
+
+    expect(pending).toBeDefined();
+    expect(pending!.isPending).toBe(true);
+    expect(pending!.attachments).toBe(pendingAttachments);
+    // No execution record yet — presigning must not be attempted.
+    expect(pending!.executionId).toBeUndefined();
+  });
+
+  it("keeps the attachments on a FAILED pending bubble (evidence of what Retry re-sends)", () => {
+    const items = buildThreadItems(
+      [],
+      null,
+      "Here is a sketch.",
+      false,
+      undefined,
+      undefined,
+      true, // pendingMessageFailed
+      false,
+      false,
+      false,
+      pendingAttachments,
+    );
+    const pending = pendingItem(items);
+
+    expect(pending).toBeDefined();
+    expect(pending!.isFailed).toBe(true);
+    expect(pending!.attachments).toBe(pendingAttachments);
+  });
+
+  it("stamps NO attachments on the pending bubble when the submit had none", () => {
+    const items = buildThreadItems(
+      [],
+      null,
+      "Plain follow-up.",
+      false,
+      undefined,
+      undefined,
+      false,
+      false,
+      false,
+      false,
+      [],
+    );
+    const pending = pendingItem(items);
+
+    expect(pending).toBeDefined();
+    expect(pending!.attachments).toBeUndefined();
+  });
+});

package/src/execution/index.ts

@@ -191,6 +191,12 @@ export type { SubAgentSectionProps } from "./SubAgentSection.js";
 export { MessageEntry } from "./MessageEntry.js";
 export type { MessageEntryProps } from "./MessageEntry.js";
 
+export { MessageAttachments } from "./MessageAttachments.js";
+export type {
+  MessageAttachmentsProps,
+  MessageAttachmentView,
+} from "./MessageAttachments.js";
+
 export { MessageThread } from "./MessageThread.js";
 export type {
   MessageThreadProps,

package/src/github/__tests__/decodeGitHubContent.test.ts

@@ -5,7 +5,10 @@ import {
   bytesToText,
   normalizeGitHubContent,
 } from "../decodeGitHubContent";
-import { MAX_WORKSPACE_FILE_READ_BYTES } from "../../workspace/WorkspaceFileReader";
+import {
+  MAX_WORKSPACE_FILE_READ_BYTES,
+  MAX_WORKSPACE_IMAGE_READ_BYTES,
+} from "../../workspace/WorkspaceFileReader";
 
 function utf8(s: string): Uint8Array {
   return new TextEncoder().encode(s);
@@ -99,4 +102,42 @@ describe("normalizeGitHubContent", () => {
     expect(result.truncated).toBeUndefined();
     expect(result.text).toHaveLength(MAX_WORKSPACE_FILE_READ_BYTES);
   });
+
+  // -------------------------------------------------------------------
+  // Whole-image delivery (stigmer/stigmer#379)
+  // -------------------------------------------------------------------
+
+  it("delivers whole image bytes when the binary file has an image MIME", () => {
+    const bytes = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x00]);
+    const result = normalizeGitHubContent(bytes, bytes.length, "image/png");
+
+    expect(result.isBinary).toBe(true);
+    expect(result.encoding).toBe("base64");
+    expect(result.bytes).toBe(bytes);
+  });
+
+  it("withholds bytes from binary content without an image MIME", () => {
+    const result = normalizeGitHubContent(new Uint8Array([0x00, 0x01]), 2, null);
+    expect(result.isBinary).toBe(true);
+    expect(result.bytes).toBeUndefined();
+  });
+
+  it("withholds bytes from an image beyond the whole-image ceiling", () => {
+    // All-zero bytes trip the NUL sniff; one byte over the ceiling means the
+    // image cannot be delivered whole, so no bytes ride along.
+    const oversized = new Uint8Array(MAX_WORKSPACE_IMAGE_READ_BYTES + 1);
+    const result = normalizeGitHubContent(oversized, oversized.length, "image/png");
+
+    expect(result.isBinary).toBe(true);
+    expect(result.bytes).toBeUndefined();
+  });
+
+  it("keeps a text file that merely claims an image extension on the text path", () => {
+    const bytes = utf8("not really a png");
+    const result = normalizeGitHubContent(bytes, bytes.length, "image/png");
+
+    expect(result.text).toBe("not really a png");
+    expect(result.isBinary).toBe(false);
+    expect(result.bytes).toBeUndefined();
+  });
 });

package/src/github/decodeGitHubContent.ts

@@ -4,6 +4,7 @@
 
 import {
   MAX_WORKSPACE_FILE_READ_BYTES,
+  MAX_WORKSPACE_IMAGE_READ_BYTES,
   type WorkspaceFileContent,
 } from "../workspace/WorkspaceFileReader.js";
 
@@ -51,17 +52,33 @@ export function bytesToText(bytes: Uint8Array): string | null {
  * Turn decoded bytes into a {@link WorkspaceFileContent}, applying binary
  * detection and the shared 1 MB display cap.
  *
- * @param bytes    the full decoded bytes as delivered by GitHub
- * @param fullSize the file's true size in bytes (GitHub's `size` field), which
- *                 may exceed `bytes.length` when the caller has already capped
- *                 the download — reported verbatim as `size`.
+ * @param bytes     the full decoded bytes as delivered by GitHub
+ * @param fullSize  the file's true size in bytes (GitHub's `size` field), which
+ *                  may exceed `bytes.length` when the caller has already capped
+ *                  the download — reported verbatim as `size`.
+ * @param imageMime the file's image MIME type per `workspaceImageMimeType`, or
+ *                  `null`. When set and the bytes are binary, the *complete*
+ *                  bytes ride along for the viewer's image arm
+ *                  (stigmer/stigmer#379) — GitHub always delivers whole files
+ *                  on this path, so the bytes in hand ARE the image.
  */
 export function normalizeGitHubContent(
   bytes: Uint8Array,
   fullSize: number,
+  imageMime: string | null = null,
 ): WorkspaceFileContent {
   if (detectBinary(bytes)) {
-    return { text: null, isBinary: true, size: fullSize, encoding: "base64" };
+    // Gate on the binary sniff, not extension alone: a text file that merely
+    // *claims* .png keeps rendering as text below, exactly as before.
+    const deliverImage =
+      imageMime !== null && bytes.length <= MAX_WORKSPACE_IMAGE_READ_BYTES;
+    return {
+      text: null,
+      isBinary: true,
+      size: fullSize,
+      encoding: "base64",
+      ...(deliverImage ? { bytes } : {}),
+    };
   }
 
   // Decode the full buffer, then cap the resulting *string* — capping the bytes