@stigmer/react 3.8.0 → 3.10.0

package/src/execution/MessageAttachments.tsx

@@ -0,0 +1,364 @@
+"use client";
+
+import { useState } from "react";
+import { cn } from "@stigmer/theme";
+import { AttachmentImageLightbox } from "../attachment/AttachmentImageLightbox.js";
+import { UNSTYLED_BUTTON } from "../internal/form-primitives.js";
+import { useArtifactDownload } from "./useArtifactDownload.js";
+import { useArtifactDownloadUrl } from "./useArtifactDownloadUrl.js";
+
+/**
+ * The minimal display shape of a submitted attachment.
+ *
+ * Structurally satisfied by BOTH sources a human turn can carry — the
+ * `Attachment` proto on a persisted execution's `spec.attachments` and the
+ * `AttachmentInput` a just-submitted (pending) turn holds — so the thread
+ * renders either without conversion code or a duplicated type (DD-007).
+ */
+export interface MessageAttachmentView {
+  /** Original filename, e.g. `"screenshot.png"`. */
+  readonly filename?: string;
+  /** MIME type, e.g. `"image/png"`. Drives the image-vs-document treatment. */
+  readonly contentType?: string;
+  /** Storage key (`attachments/{ulid}/{filename}`) minted at upload time. */
+  readonly storageKey?: string;
+}
+
+/** Props for {@link MessageAttachments}. */
+export interface MessageAttachmentsProps {
+  /** The turn's submitted attachments, in submission order. */
+  readonly attachments: readonly MessageAttachmentView[];
+  /**
+   * The execution the attachments were submitted to. Enables the byte-backed
+   * affordances — image previews (presigned URL) and document downloads.
+   * Omit for the optimistic pending bubble (no execution record yet) and the
+   * failed-send bubble (no record ever): images render as inert glyph tiles
+   * and documents as inert chips until a real turn brings the presign seam.
+   */
+  readonly executionId?: string;
+  /** Additional CSS class names for the row container. */
+  readonly className?: string;
+}
+
+/**
+ * The attachment row on a human turn: the durable evidence of what files were
+ * sent with the message (stigmer/stigmer#372).
+ *
+ * Image attachments render as preview-only thumbnail tiles — the image IS the
+ * chip, no filename text (the name stays in the tooltip, the accessible
+ * label, and the lightbox header), click-to-open in the shared
+ * {@link AttachmentImageLightbox} — and documents as compact click-to-download
+ * filename chips. Both follow the composer chip grammar
+ * ({@link AttachmentChipList}) so a file looks the same before and after
+ * send, but this is deliberately a separate component: the composer chip is
+ * interactive and upload-phase-bound over a local `File`, while this row is
+ * read-only over the execution record, with bytes resolved on demand from
+ * the stable storage key via presigned URLs (the `OutputRefImage` pattern —
+ * the local `File` is gone after submit).
+ *
+ * Purely presentational plus on-demand URL minting — no required wiring.
+ * All visual properties flow through `--stgm-*` tokens.
+ */
+export function MessageAttachments({
+  attachments,
+  executionId,
+  className,
+}: MessageAttachmentsProps) {
+  // One lightbox instance serves the whole row, tracked by storage key
+  // (direct identity). It mounts OUTSIDE the role="list" container — a
+  // <dialog> is not valid inside the chips' <span> elements, and a
+  // non-listitem child inside the list would break its a11y ownership
+  // (same reasoning as the composer's chip list).
+  const [previewKey, setPreviewKey] = useState<string | null>(null);
+  const previewed =
+    previewKey !== null
+      ? (attachments.find((a) => a.storageKey === previewKey) ?? null)
+      : null;
+
+  if (attachments.length === 0) return null;
+
+  return (
+    <>
+      {/* items-center is load-bearing: image tiles (h-14) and document chips
+          (~h-6) share this row, and flexbox's default stretch alignment
+          would balloon the document chips to tile height. */}
+      <div
+        className={cn("flex flex-wrap items-center gap-1.5", className)}
+        role="list"
+        aria-label="Submitted attachments"
+      >
+        {attachments.map((attachment, i) => {
+          const isImage = attachment.contentType?.startsWith("image/") ?? false;
+          const key = attachment.storageKey ?? `${displayName(attachment)}-${i}`;
+          if (isImage && executionId && attachment.storageKey) {
+            return (
+              <ImagePreviewChip
+                key={key}
+                attachment={attachment}
+                executionId={executionId}
+                onPreview={() => setPreviewKey(attachment.storageKey!)}
+              />
+            );
+          }
+          if (isImage && !executionId) {
+            // No execution record — the optimistic pending bubble or a
+            // failed send. The tile keeps the image grammar but stays
+            // STATIC (a glyph, not a pulse): a failed send never gets an
+            // executionId, so a pulse here would be a permanent false
+            // "loading" signal. On the pending bubble the real turn lands
+            // under the same bridge key and brings the presign seam.
+            return <ImageGlyphTile key={key} name={displayName(attachment)} />;
+          }
+          return (
+            <DocumentChip
+              key={key}
+              attachment={attachment}
+              executionId={executionId}
+            />
+          );
+        })}
+      </div>
+      {previewed && executionId && previewed.storageKey && (
+        <AttachmentPreviewLightbox
+          attachment={previewed}
+          executionId={executionId}
+          onClose={() => setPreviewKey(null)}
+        />
+      )}
+    </>
+  );
+}
+
+/**
+ * Display name for an attachment: the filename, falling back to the storage
+ * key's basename (`attachments/{ulid}/{filename}` always ends in it).
+ */
+function displayName(attachment: MessageAttachmentView): string {
+  if (attachment.filename) return attachment.filename;
+  const key = attachment.storageKey ?? "";
+  const base = key.slice(key.lastIndexOf("/") + 1);
+  return base || "attachment";
+}
+
+// ---------------------------------------------------------------------------
+// Image attachment — a preview-only tile mirroring the composer's grammar
+// ---------------------------------------------------------------------------
+
+/**
+ * The preview-only image tile: the thumbnail IS the chip, minted from the
+ * stable storage key at view time — no filename text (the name stays in the
+ * tooltip, the accessible label, and the lightbox header). If the URL can't
+ * be resolved (revoked storage, transient API failure), the chip degrades to
+ * the document treatment — a generic icon with the download affordance —
+ * never a broken-image glyph.
+ */
+function ImagePreviewChip({
+  attachment,
+  executionId,
+  onPreview,
+}: {
+  readonly attachment: MessageAttachmentView;
+  readonly executionId: string;
+  readonly onPreview: () => void;
+}) {
+  const { url, error } = useArtifactDownloadUrl(
+    executionId,
+    attachment.storageKey ?? null,
+  );
+  const name = displayName(attachment);
+
+  if (error) {
+    return <DocumentChip attachment={attachment} executionId={executionId} />;
+  }
+
+  return (
+    <span role="listitem" aria-label={name} title={name} className="inline-flex">
+      {/* The whole tile is the preview target. UNSTYLED_BUTTON is
+          load-bearing: without it the tile shows the UA's default button
+          box in preflight-less hosts (see the constant). */}
+      <button
+        type="button"
+        onClick={onPreview}
+        aria-label={`Preview ${name}`}
+        className={cn(
+          UNSTYLED_BUTTON,
+          "relative block h-14 w-14 overflow-hidden rounded-md focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        )}
+      >
+        {url ? (
+          <img
+            src={url}
+            alt=""
+            aria-hidden="true"
+            loading="lazy"
+            className="h-full w-full object-cover"
+          />
+        ) : (
+          // Pulse placeholder while the presigned URL is minted — pulse
+          // means work is genuinely in flight (contrast ImageGlyphTile).
+          // Same footprint as the image, so no layout shift.
+          <span
+            className="block h-full w-full animate-pulse bg-muted"
+            aria-hidden="true"
+          />
+        )}
+      </button>
+    </span>
+  );
+}
+
+/**
+ * The inert image tile for a turn with no execution record yet (optimistic
+ * pending bubble) or ever (failed send). Keeps the image grammar — same
+ * footprint as {@link ImagePreviewChip} — but shows a STATIC glyph, not a
+ * pulse: a pulse promises bytes that, on a failed send, will never arrive.
+ */
+function ImageGlyphTile({ name }: { readonly name: string }) {
+  return (
+    <span
+      role="listitem"
+      aria-label={name}
+      title={name}
+      className="inline-flex h-14 w-14 items-center justify-center rounded-md bg-muted-subtle"
+    >
+      <ImageGlyph />
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Document attachment — compact chip, click-to-download
+// ---------------------------------------------------------------------------
+
+/**
+ * The compact treatment for documents (and for any attachment before its
+ * execution record exists). With an execution id, the chip is a download
+ * button — a fresh URL is minted at click time via {@link useArtifactDownload},
+ * saved under the original filename. Without one (pending bubble), it is an
+ * inert label: evidence the file was sent, affordances once the record lands.
+ */
+function DocumentChip({
+  attachment,
+  executionId,
+}: {
+  readonly attachment: MessageAttachmentView;
+  readonly executionId?: string;
+}) {
+  const { download, isDownloading } = useArtifactDownload(executionId ?? null);
+  const name = displayName(attachment);
+  const downloadable = executionId != null && !!attachment.storageKey;
+
+  const content = (
+    <>
+      <FileGlyph />
+      <span className="min-w-0 truncate">{name}</span>
+    </>
+  );
+
+  return (
+    <span
+      role="listitem"
+      aria-label={name}
+      title={name}
+      className="inline-flex max-w-[200px] items-center rounded-md bg-muted-subtle px-2 py-0.5 text-xs text-foreground"
+    >
+      {downloadable ? (
+        <button
+          type="button"
+          onClick={() => void download(attachment.storageKey!, name)}
+          disabled={isDownloading}
+          aria-label={`Download ${name}`}
+          className={cn(
+            UNSTYLED_BUTTON,
+            "flex min-w-0 items-center gap-1 rounded-sm text-inherit [font:inherit] hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+            isDownloading && "opacity-70",
+          )}
+        >
+          {content}
+        </button>
+      ) : (
+        <span className="flex min-w-0 items-center gap-1">{content}</span>
+      )}
+    </span>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Lightbox bridge
+// ---------------------------------------------------------------------------
+
+/**
+ * Feeds the previewed attachment's presigned URL to the shared
+ * {@link AttachmentImageLightbox}. The URL hook is cross-mount cached by
+ * storage key (DD-014), so opening the lightbox reuses the thumbnail's minted
+ * URL instead of a second RPC; `src` is `null` for at most the first frame.
+ */
+function AttachmentPreviewLightbox({
+  attachment,
+  executionId,
+  onClose,
+}: {
+  readonly attachment: MessageAttachmentView;
+  readonly executionId: string;
+  readonly onClose: () => void;
+}) {
+  const { url } = useArtifactDownloadUrl(
+    executionId,
+    attachment.storageKey ?? null,
+  );
+
+  return (
+    <AttachmentImageLightbox
+      src={url}
+      filename={displayName(attachment)}
+      open
+      onClose={onClose}
+    />
+  );
+}
+
+/** Generic picture glyph for the inert {@link ImageGlyphTile}. */
+function ImageGlyph() {
+  return (
+    <svg
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0 text-muted-foreground"
+      aria-hidden="true"
+    >
+      <rect x="3" y="3" width="18" height="18" rx="2" />
+      <circle cx="8.5" cy="8.5" r="1.5" />
+      <path d="M21 15l-5-5L5 21" />
+    </svg>
+  );
+}
+
+/**
+ * Generic document glyph — the same geometry as the composer chip's icon so
+ * the two surfaces read as one family.
+ */
+function FileGlyph() {
+  return (
+    <svg
+      width="10"
+      height="10"
+      viewBox="0 0 14 14"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className="shrink-0 text-muted-foreground"
+      aria-hidden="true"
+    >
+      <path d="M8 1H4C3.45 1 3 1.45 3 2V12C3 12.55 3.45 13 4 13H10C10.55 13 11 12.55 11 12V4L8 1Z" />
+      <path d="M8 1V4H11" />
+    </svg>
+  );
+}

package/src/execution/MessageEntry.tsx

@@ -13,6 +13,10 @@ import {
   unwrapEnclosingMarkdownFence,
 } from "../internal/markdown-components.js";
 import { InteractionModeBadge } from "./InteractionModeBadge.js";
+import {
+  MessageAttachments,
+  type MessageAttachmentView,
+} from "./MessageAttachments.js";
 import { PlanDocumentMessage } from "./PlanDocumentMessage.js";
 import { useRenderTracer } from "../internal/dev/index.js";
 
@@ -48,6 +52,23 @@ export interface MessageEntryProps {
    * non-human messages.
    */
   readonly interactionMode?: InteractionMode;
+  /**
+   * The turn's submitted attachments, stamped by the thread builder on
+   * `MESSAGE_HUMAN` bubbles from the execution's `spec.attachments` (or the
+   * pending submit context). Renders as a {@link MessageAttachments} row
+   * above the prose. Ignored for non-human messages.
+   *
+   * A `MessageEntry` slot override that delegates to the built-in inherits
+   * attachment rendering; one that ignores this prop renders text only.
+   */
+  readonly attachments?: readonly MessageAttachmentView[];
+  /**
+   * The execution the attachments belong to — enables their byte-backed
+   * affordances (image previews, document downloads) via presigned URLs.
+   * Absent on the optimistic pending bubble, where attachments render as
+   * inert chips until the real execution record replaces it.
+   */
+  readonly executionId?: string;
 }
 
 /**
@@ -80,6 +101,8 @@ export const MessageEntry = memo(function MessageEntry({
   onEdit,
   isPlanDocument,
   interactionMode,
+  attachments,
+  executionId,
 }: MessageEntryProps) {
   useRenderTracer("MessageEntry", {
     messageType: message.type,
@@ -95,6 +118,8 @@ export const MessageEntry = memo(function MessageEntry({
           className={className}
           onEdit={onEdit}
           interactionMode={interactionMode}
+          attachments={attachments}
+          executionId={executionId}
         />
       );
     case MessageType.MESSAGE_AI:
@@ -132,11 +157,15 @@ function HumanMessage({
   className,
   onEdit,
   interactionMode,
+  attachments,
+  executionId,
 }: {
   content: string;
   className?: string;
   onEdit?: () => void;
   interactionMode?: InteractionMode;
+  attachments?: readonly MessageAttachmentView[];
+  executionId?: string;
 }) {
   return (
     <div
@@ -152,6 +181,15 @@ function HumanMessage({
       {interactionMode !== undefined && (
         <InteractionModeBadge mode={interactionMode} className="mb-1.5" />
       )}
+      {/* The evidence a file rode with this turn (#372) — above the prose,
+          mirroring the composer's chips-above-input layout. */}
+      {attachments && attachments.length > 0 && (
+        <MessageAttachments
+          attachments={attachments}
+          executionId={executionId}
+          className="mb-2"
+        />
+      )}
       <p className="text-sm text-foreground whitespace-pre-wrap">{content}</p>
       {onEdit && (
         <button

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"