@stigmer/react 3.9.0 → 3.10.0

package/src/github/useGitHubFileReader.ts

@@ -4,6 +4,7 @@ import { useCallback } from "react";
 import type { WorkspaceEntry } from "../workspace/useWorkspaceEntries.js";
 import {
   WorkspaceFileNotFoundError,
+  workspaceImageMimeType,
   type WorkspaceFileContent,
   type WorkspaceFileReader,
 } from "../workspace/WorkspaceFileReader.js";
@@ -116,12 +117,16 @@ export function useGitHubFileReader(
 
       const file = data as GitHubContentsFile;
       if (file.encoding === "base64") {
-        return normalizeGitHubContent(base64ToBytes(file.content), file.size);
+        return normalizeGitHubContent(
+          base64ToBytes(file.content),
+          file.size,
+          workspaceImageMimeType(path),
+        );
       }
 
       // encoding: "none" is GitHub's signal that the file exceeds the Contents
       // API's ~1 MB cap; the bytes live only behind the Blob API.
-      return readViaBlob(parsed, file, token);
+      return readViaBlob(parsed, file, path, token);
     },
     [token],
   );
@@ -138,6 +143,7 @@ export function useGitHubFileReader(
 async function readViaBlob(
   parsed: { owner: string; repo: string },
   file: GitHubContentsFile,
+  path: string,
   token: string,
 ): Promise<WorkspaceFileContent> {
   // Above the ceiling we never download — GitHub already told us the size, so
@@ -161,5 +167,9 @@ async function readViaBlob(
   }
 
   const blob: GitHubBlob = await resp.json();
-  return normalizeGitHubContent(base64ToBytes(blob.content), blob.size);
+  return normalizeGitHubContent(
+    base64ToBytes(blob.content),
+    blob.size,
+    workspaceImageMimeType(path),
+  );
 }

package/src/index.ts

@@ -71,7 +71,9 @@ export {
   useWorkspaceContentSearch,
   useWorkspaceSources,
   MAX_WORKSPACE_FILE_READ_BYTES,
+  MAX_WORKSPACE_IMAGE_READ_BYTES,
   WorkspaceFileNotFoundError,
+  workspaceImageMimeType,
   WorkspaceEditor,
   WorkspaceFileSearch,
   WorkspaceContentSearch,
@@ -1379,6 +1381,7 @@ export {
   ConversationComposer,
   useConversation,
   useConversationList,
+  useConversationMediaUrl,
   useConversationTimeline,
   useConversationParticipation,
   useConversationsWantsHumanCount,
@@ -1409,6 +1412,8 @@ export type {
   UseConversationReturn,
   UseConversationListOptions,
   UseConversationListReturn,
+  UseConversationMediaUrlOptions,
+  UseConversationMediaUrlReturn,
   UseConversationTimelineOptions,
   UseConversationTimelineReturn,
   ConversationCommand,

package/src/internal/form-primitives.tsx

@@ -8,6 +8,20 @@ import { cn } from "@stigmer/theme";
 // Internal — never exported from the package barrel.
 // ---------------------------------------------------------------------------
 
+/**
+ * Neutralizes the UA's default `<button>` styling (buttonface background,
+ * padding, default cursor). The SDK's scoped preflight in `styles.css`
+ * resets only borders/box-sizing; in the console and desktop app the host's
+ * global Tailwind preflight covers the rest, but a preflight-less host
+ * (docs tours, third-party embeds) would otherwise render every bare button
+ * as a gray UA box. Font is NOT reset here — callers that render text set
+ * `[font:inherit]` or explicit text utilities themselves.
+ *
+ * Applies to buttons that are styled entirely by their content (chips,
+ * icon-only affordances), not to the themed button components.
+ */
+export const UNSTYLED_BUTTON = "cursor-pointer bg-transparent p-0";
+
 /** Standard text-input styling for the operator consoles. */
 export const INPUT_CLASSES = cn(
   "w-full rounded-md border border-input bg-background px-2.5 py-1.5 text-xs text-foreground",

package/src/session/SessionViewer.tsx

@@ -795,6 +795,7 @@ const ConversationColumn = memo(function ConversationColumn({
         executions={conv.completedExecutions}
         activeStreamExecution={conv.activeStreamExecution}
         pendingUserMessage={conv.pendingUserMessage}
+        pendingAttachments={conv.pendingAttachments}
         pendingMessageFailed={!!conv.sendError && !!conv.pendingUserMessage}
         // Observers get a pure transcript: every interaction affordance
         // (retry, approvals, edit, build-from-plan) is opt-in via its

package/src/session/__tests__/useSessionConversation.test.tsx

@@ -260,6 +260,68 @@ describe("useSessionConversation", () => {
     expect(result.current.pendingUserMessage).toBe("Hello agent");
   });
 
+  it("sendFollowUp carries the submit's attachments as pendingAttachments, cleared with the first snapshot", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    const newExec = makeExecution("new-exec", ExecutionPhase.EXECUTION_PENDING);
+    newExec.metadata!.id = "new-exec";
+    methods.executionCreate.mockResolvedValue(newExec);
+
+    const newStream = createControllableStream<AgentExecution>();
+    methods.subscribe.mockReturnValue(newStream.generator);
+
+    const attachments = [
+      { filename: "sketch.png", storageKey: "attachments/01AAA/sketch.png", contentType: "image/png" },
+    ];
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("Here is a sketch", { attachments });
+    });
+
+    // The optimistic turn carries BOTH facets — text and files (#372).
+    expect(result.current.pendingUserMessage).toBe("Here is a sketch");
+    expect(result.current.pendingAttachments).toBe(attachments);
+
+    act(() => {
+      newStream.push(
+        makeExecution("new-exec", ExecutionPhase.EXECUTION_IN_PROGRESS),
+      );
+    });
+
+    // Both clear together once the real execution record takes over.
+    await waitFor(() => {
+      expect(result.current.pendingUserMessage).toBeNull();
+      expect(result.current.pendingAttachments).toBeNull();
+    });
+  });
+
+  it("keeps pendingAttachments when the send fails (the chips are what Retry re-sends)", async () => {
+    methods.listBySession.mockResolvedValue({ entries: [] });
+    methods.executionCreate.mockRejectedValue(new Error("create boom"));
+
+    const attachments = [
+      { filename: "notes.txt", storageKey: "attachments/01BBB/notes.txt", contentType: "text/plain" },
+    ];
+
+    const { result } = renderHook(
+      () => useSessionConversation("session-1", "org"),
+      { wrapper: createWrapper(mockStigmer) },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    await act(async () => {
+      await result.current.sendFollowUp("keep my files", { attachments });
+    });
+
+    expect(result.current.sendError?.message).toBe("create boom");
+    expect(result.current.pendingAttachments).toBe(attachments);
+  });
+
   it("sendFollowUp creates execution via the SDK", async () => {
     methods.listBySession.mockResolvedValue({ entries: [] });
     const newExec = makeExecution("new-exec", ExecutionPhase.EXECUTION_PENDING);

package/src/session/useSessionConversation.ts

@@ -213,6 +213,14 @@ export interface UseSessionConversationReturn {
    * {@link sendError} to render the turn as failed with a retry control.
    */
   readonly pendingUserMessage: string | null;
+  /**
+   * The attachments submitted with {@link pendingUserMessage}, so the
+   * optimistic bubble shows the turn's files, not just its text
+   * (stigmer/stigmer#372). Set and cleared in lockstep with the message —
+   * including retention on a failed send, where the chips are the evidence
+   * of what Retry will re-send. Wire to `MessageThread.pendingAttachments`.
+   */
+  readonly pendingAttachments: readonly AttachmentInput[] | null;
 
   /** Current workspace entries from the session spec. Empty array when session is not loaded. */
   readonly workspaceEntries: readonly ProtoWorkspaceEntry[];
@@ -439,6 +447,12 @@ export function useSessionConversation(
   const [pendingUserMessage, setPendingUserMessage] = useState<string | null>(
     null,
   );
+  // The pending message's attachments, kept in lockstep with the text: one
+  // pending turn, two facets. Held separately (not an object) so existing
+  // pendingUserMessage consumers keep their string contract.
+  const [pendingAttachments, setPendingAttachments] = useState<
+    readonly AttachmentInput[] | null
+  >(null);
   // Dedicated send-failure state, distinct from the create hook's internal
   // error so it can also cover the session.update() path. The last send's
   // arguments are captured for an exact retry.
@@ -507,8 +521,9 @@ export function useSessionConversation(
   useEffect(() => {
     if (!stream.execution) return;
     if (pendingUserMessage) setPendingUserMessage(null);
+    if (pendingAttachments) setPendingAttachments(null);
     if (sendError) setSendError(null);
-  }, [pendingUserMessage, sendError, stream.execution]);
+  }, [pendingUserMessage, pendingAttachments, sendError, stream.execution]);
 
   // Refetch executions when stream reaches a terminal phase so the
   // fetched list reflects the completed status and listActiveId clears.
@@ -620,6 +635,7 @@ export function useSessionConversation(
       // renders the failed-with-retry bubble instead of vanishing.
       if (!options?.buildFromPlan) {
         setPendingUserMessage(message);
+        setPendingAttachments(options?.attachments ?? null);
       }
 
       try {
@@ -666,8 +682,10 @@ export function useSessionConversation(
         // pendingUserMessage) so the turn renders as failed-with-retry instead
         // of vanishing. Covers both the update() and create() paths. For a
         // build turn this is the FIRST time the message is set — failure is
-        // the one case where its label must become visible.
+        // the one case where its label must become visible. The attachments
+        // ride along: the failed bubble's chips are what Retry will re-send.
         setPendingUserMessage(message);
+        setPendingAttachments(options?.attachments ?? null);
         setSendError(toError(err));
         if (process.env.NODE_ENV !== "production") {
           console.error("[useSessionConversation] sendFollowUp failed:", err);
@@ -753,6 +771,7 @@ export function useSessionConversation(
     retryLastSend,
 
     pendingUserMessage,
+    pendingAttachments,
 
     workspaceEntries,
     mcpServerUsages,

package/src/workspace/FileViewer.tsx

@@ -5,6 +5,7 @@ import {
   useCallback,
   useEffect,
   useImperativeHandle,
+  useMemo,
   useRef,
   useState,
   type KeyboardEvent,
@@ -15,15 +16,19 @@ import {
   FileChangeCaptureLevel,
   FileChangeType,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { AttachmentImageLightbox } from "../attachment/AttachmentImageLightbox.js";
+import { useObjectUrl } from "../attachment/useObjectUrl.js";
 import { ArtifactContentRenderer } from "../execution/ArtifactContentRenderer.js";
 import { FileChangeDiff } from "../execution/FileChangesView.js";
 import { useFileChangeContent } from "../execution/useFileChangeContent.js";
+import { UNSTYLED_BUTTON } from "../internal/form-primitives.js";
 import type { RevealTarget } from "../internal/useRevealLine.js";
 import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
 import { useWorkspaceFileContent } from "./useWorkspaceFileContent.js";
 import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
 import {
   WorkspaceFileNotFoundError,
+  workspaceImageMimeType,
   type WorkspaceFileReader,
 } from "./WorkspaceFileReader.js";
 
@@ -431,6 +436,23 @@ function FileViewerBody({
     return <MessageState>Content not available for preview.</MessageState>;
   }
 
+  // A binary that is a renderable image, delivered whole by the reader,
+  // shows the picture instead of the binary notice (stigmer/stigmer#379).
+  // The MIME gate re-derives from the path: bytes without a recognized image
+  // extension still fall through to the notice.
+  const imageMime = workspaceImageMimeType(basename);
+  if (content.bytes && imageMime) {
+    return (
+      <ImageFileContent
+        bytes={content.bytes}
+        mime={imageMime}
+        basename={basename}
+        size={content.size}
+        change={change}
+      />
+    );
+  }
+
   if (content.isBinary) {
     return (
       <MessageState>
@@ -469,6 +491,93 @@ function FileViewerBody({
   );
 }
 
+/**
+ * Inline image rendering for a workspace file whose reader delivered whole
+ * image bytes (stigmer/stigmer#379). The bytes become an object URL for the
+ * component's lifetime; clicking the image opens the shared
+ * {@link AttachmentImageLightbox} at full size — the same viewer attachment
+ * chips and conversation media use, so pictures behave identically across
+ * surfaces. If the browser cannot decode the bytes (a corrupt file behind an
+ * image extension), the component degrades to the binary notice — never a
+ * broken-image glyph.
+ */
+function ImageFileContent({
+  bytes,
+  mime,
+  basename,
+  size,
+  change,
+}: {
+  readonly bytes: Uint8Array;
+  readonly mime: string;
+  readonly basename: string;
+  readonly size: number;
+  readonly change?: FileChange;
+}) {
+  // Memo (not effect) is correct for the Blob — it holds no OS resource; the
+  // object URL over it is effect-managed inside useObjectUrl.
+  const blob = useMemo(() => new Blob([bytes as BlobPart], { type: mime }), [bytes, mime]);
+  const url = useObjectUrl(blob);
+  const [loadFailed, setLoadFailed] = useState(false);
+  const [lightboxOpen, setLightboxOpen] = useState(false);
+
+  if (loadFailed) {
+    return (
+      <MessageState>
+        Binary file — not shown{size ? ` (${formatBytes(size)})` : ""}.
+      </MessageState>
+    );
+  }
+
+  return (
+    <>
+      {change && (
+        <p className="border-b border-border-muted px-4 py-1.5 text-[0.65rem] text-muted-foreground">
+          Live — may differ from the reviewed change.
+        </p>
+      )}
+      <div className="flex flex-col items-center gap-2 p-4">
+        {url ? (
+          // UNSTYLED_BUTTON is load-bearing: without it the button shows the
+          // UA's default box in preflight-less hosts (see the constant).
+          <button
+            type="button"
+            onClick={() => setLightboxOpen(true)}
+            aria-label={`Preview ${basename} at full size`}
+            className={cn(
+              UNSTYLED_BUTTON,
+              "max-w-full rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            )}
+          >
+            <img
+              src={url}
+              alt={basename}
+              onError={() => setLoadFailed(true)}
+              className="max-h-[70vh] max-w-full rounded-md border border-border object-contain"
+            />
+          </button>
+        ) : (
+          // One-frame placeholder until the object-URL effect runs.
+          <div
+            className="h-48 w-72 max-w-full animate-pulse rounded-md bg-muted"
+            aria-hidden="true"
+          />
+        )}
+        <p className="text-[0.65rem] tabular-nums text-muted-foreground">
+          {mime}
+          {size ? ` · ${formatBytes(size)}` : ""}
+        </p>
+      </div>
+      <AttachmentImageLightbox
+        src={url}
+        filename={basename}
+        open={lightboxOpen}
+        onClose={() => setLightboxOpen(false)}
+      />
+    </>
+  );
+}
+
 /**
  * The captured-content fallback: renders a change's after-side text (the
  * bytes the session already holds — inline or offloaded to artifact storage)

package/src/workspace/WorkspaceFileReader.ts

@@ -12,12 +12,57 @@ import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
  */
 export const MAX_WORKSPACE_FILE_READ_BYTES = 1_048_576; // 1 MiB
 
+/**
+ * Byte ceiling for delivering a workspace *image* in full (stigmer/stigmer#379).
+ *
+ * Deliberately larger than {@link MAX_WORKSPACE_FILE_READ_BYTES}: text
+ * degrades gracefully when truncated, an image does not — a partial PNG is
+ * useless, so readers deliver image bytes whole or not at all. 10 MiB matches
+ * the GitHub reader's existing blob-fetch ceiling; the desktop native reader
+ * mirrors it as `MAX_IMAGE_READ_BYTES` in `src-tauri/src/workspace.rs`.
+ */
+export const MAX_WORKSPACE_IMAGE_READ_BYTES = 10 * 1024 * 1024; // 10 MiB
+
+/**
+ * Raster image formats the viewer renders inline, keyed by file extension.
+ *
+ * SVG is deliberately absent: it decodes as UTF-8 and flows through the text
+ * path, where a workspace browser wants it — it is source to inspect, not a
+ * picture (matching editor convention). The desktop native reader mirrors
+ * this list as `IMAGE_EXTENSIONS` in `src-tauri/src/workspace.rs`.
+ */
+const IMAGE_MIME_BY_EXTENSION: Readonly<Record<string, string>> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  avif: "image/avif",
+  bmp: "image/bmp",
+  ico: "image/x-icon",
+};
+
+/**
+ * MIME type for a workspace path the viewer can render as an inline image,
+ * or `null` for everything else. The single policy point shared by readers
+ * (deciding whether to attach {@link WorkspaceFileContent.bytes}) and the
+ * viewer (deciding whether to render an image arm) — extension-based, since
+ * workspace reads have no server-provided content type.
+ */
+export function workspaceImageMimeType(path: string): string | null {
+  const dot = path.lastIndexOf(".");
+  if (dot === -1) return null;
+  const ext = path.slice(dot + 1).toLowerCase();
+  return IMAGE_MIME_BY_EXTENSION[ext] ?? null;
+}
+
 /**
  * Decoded content (plus metadata) for a single workspace file.
  *
  * `text` is `null` whenever the bytes are not displayable as UTF-8 — either
  * binary (`isBinary`) or an undecodable byte sequence (`encoding: "unknown"`).
- * The renderer uses `isBinary`/`text === null` for its fallback state.
+ * The renderer uses `isBinary`/`text === null` for its fallback state, except
+ * when `bytes` carries a renderable image.
  */
 export interface WorkspaceFileContent {
   /** Decoded UTF-8 text, or `null` when binary or undecodable. */
@@ -30,6 +75,15 @@ export interface WorkspaceFileContent {
   readonly encoding: "utf-8" | "base64" | "none" | "unknown";
   /** `true` when `text` holds only the first {@link MAX_WORKSPACE_FILE_READ_BYTES} bytes. */
   readonly truncated?: boolean;
+  /**
+   * The complete raw bytes, populated **only** for binary files that are
+   * renderable images ({@link workspaceImageMimeType}) within
+   * {@link MAX_WORKSPACE_IMAGE_READ_BYTES} — never a channel for arbitrary
+   * binaries, and never partial (a truncated image cannot render). Optional
+   * and additive: readers that predate it remain valid, and the viewer falls
+   * back to the binary notice when it is absent (stigmer/stigmer#379).
+   */
+  readonly bytes?: Uint8Array;
 }
 
 /**

package/src/workspace/__tests__/FileViewer.test.tsx

@@ -159,6 +159,104 @@ describe("FileViewer", () => {
     );
   });
 
+  // ---------------------------------------------------------------------
+  // Image arm (stigmer/stigmer#379) — bytes delivered whole by the reader
+  // render as a picture; every gate failure falls back to the binary notice.
+  // ---------------------------------------------------------------------
+
+  const PNG_BYTES = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00]);
+
+  function imageContent(): WorkspaceFileContent {
+    return {
+      text: null,
+      isBinary: true,
+      size: PNG_BYTES.length,
+      encoding: "base64",
+      bytes: PNG_BYTES,
+    };
+  }
+
+  it("renders an image from delivered bytes instead of the binary notice", async () => {
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "assets/logo.png" }}
+        entries={ENTRIES}
+        reader={readerFor(imageContent())}
+      />,
+    );
+
+    await waitFor(() => {
+      const img = document.querySelector("img");
+      expect(img).toBeTruthy();
+      expect(img!.getAttribute("src")).toContain("blob:");
+      expect(img!.getAttribute("alt")).toBe("logo.png");
+    });
+    expect(screen.queryByText(/Binary file/i)).toBeNull();
+    // The click-to-open affordance is present and named.
+    expect(
+      screen.getByRole("button", { name: "Preview logo.png at full size" }),
+    ).toBeTruthy();
+  });
+
+  it("opens the shared lightbox at full size when the image is clicked", async () => {
+    // happy-dom does not implement the native dialog show/close methods.
+    HTMLDialogElement.prototype.showModal = function showModal() {
+      this.open = true;
+    };
+    HTMLDialogElement.prototype.close = function close() {
+      this.open = false;
+    };
+
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "assets/logo.png" }}
+        entries={ENTRIES}
+        reader={readerFor(imageContent())}
+      />,
+    );
+
+    await waitFor(() => expect(document.querySelector("img")).toBeTruthy());
+    fireEvent.click(
+      screen.getByRole("button", { name: "Preview logo.png at full size" }),
+    );
+
+    const dialog = document.querySelector("dialog");
+    expect(dialog).toBeTruthy();
+    expect(dialog!.getAttribute("aria-label")).toBe("Preview logo.png");
+  });
+
+  it("keeps the binary notice when bytes arrive for a non-image path", async () => {
+    // The viewer re-derives the MIME gate from the path: bytes on something
+    // without a recognized image extension never render as a picture.
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "data.bin" }}
+        entries={ENTRIES}
+        reader={readerFor(imageContent())}
+      />,
+    );
+
+    await waitFor(() => expect(screen.getByText(/Binary file/i)).toBeTruthy());
+    expect(document.querySelector("img")).toBeNull();
+  });
+
+  it("degrades to the binary notice when the browser cannot decode the bytes", async () => {
+    render(
+      <FileViewer
+        selectedFile={{ entryId: "e1", path: "assets/logo.png" }}
+        entries={ENTRIES}
+        reader={readerFor(imageContent())}
+      />,
+    );
+
+    await waitFor(() => expect(document.querySelector("img")).toBeTruthy());
+    fireEvent.error(document.querySelector("img")!);
+
+    // Never a broken-image glyph — the honest binary state instead.
+    await waitFor(() => expect(screen.getByText(/Binary file/i)).toBeTruthy());
+    expect(document.querySelector("img")).toBeNull();
+  });
+
   it("shows the error state with a working Retry", async () => {
     let attempt = 0;
     const reader: WorkspaceFileReader = vi.fn(async () => {

package/src/workspace/index.ts

@@ -9,7 +9,9 @@ export type {
 } from "./WorkspaceFileLister.js";
 export {
   MAX_WORKSPACE_FILE_READ_BYTES,
+  MAX_WORKSPACE_IMAGE_READ_BYTES,
   WorkspaceFileNotFoundError,
+  workspaceImageMimeType,
 } from "./WorkspaceFileReader.js";
 export type {
   WorkspaceFileContent,